⬡ Lacelium
⌘K
Version 2.x ▾

Configuration

Introduction

All of the configuration files for the Lacelium framework are stored in the config directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.

These configuration files allow you to configure things like your database connection information, your mail server information, as well as various other core configuration values such as your application URL and encryption key.

The about Command

Lacelium can display an overview of your application's configuration, drivers, and environment via the about console command:

php console about

If you're only interested in a particular section of the application overview output, you may filter for that section using the --only option:

php console about --only=environment

Or, to explore a specific configuration file's values in detail, you may use the config:show command:

php console config:show app

Environment Configuration

It is often helpful to have different configuration values based on the environment where the application is running. For example, you may wish to use a different cache driver locally than you do on your production server.

To make this a cinch, Lacelium utilizes the Dotenv PHP library. In a fresh Lacelium installation, the root directory of your application will contain a .env.example file that defines many common environment variables. During the installation process, this file will automatically be copied to .env.

Environment Variable Types

All variables in your .env files are typically parsed as strings, so some reserved values have been created to allow you to return a wider range of types from the env() function:

  • true is parsed as the boolean true
  • false is parsed as the boolean false
  • empty and null are parsed as null

Retrieving Environment Configuration

All of the variables listed in this file will be loaded into the $_ENV PHP super-global when your application receives a request. However, you may use the env helper to retrieve values from these variables in your configuration files:

'debug' => env('APP_DEBUG', false),

The second value passed to the env function is the "default value". This value will be returned if no environment variable exists for the given key.

Determining the Current Environment

The current application environment is determined via the APP_ENV variable from your .env file. You may access this value via the app_env() helper function:

$environment = app_env();

if ($environment === 'local') {
    // The environment is local
}

if ($environment === 'production') {
    // The environment is production
}

Encrypting Environment Files

Environment files can contain sensitive database passwords, encryption keys, and third-party API credentials. If you wish to commit encrypted environment files into version control, you can use the env:encrypt and env:decrypt console commands:

php console env:encrypt
php console env:decrypt --key=your-decryption-key

Accessing Configuration Values

You may easily access your configuration values using the global app_config helper function from anywhere in your application. The configuration values may be accessed using "dot" syntax, which includes the name of the file and the option you wish to access:

$value = app_config('app.timezone');

// Retrieve a default value if the configuration value does not exist:
$value = app_config('app.timezone', 'UTC');

To set configuration values at runtime, pass an array to the app_config helper:

app_config(['app.timezone' => 'America/Chicago']);

Configuration Caching

To give your application a boost in performance, you should cache all of your configuration files into a single file using the config:cache console command. This will combine all of the configuration options for your application into a single file which can be quickly loaded by the framework:

php console config:cache

You should typically run the php console config:cache command as part of your production deployment routine. If you make changes to any configuration files during development, you should clear the cache:

php console config:clear

Debug Mode

The debug option in your config/app.php configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the APP_DEBUG environment variable, which is stored in your .env file.

For local development, you should set the APP_DEBUG environment variable to true. In your production environment, this value should always be false. If the variable is set to true in production, you risk exposing sensitive configuration values to your application's end users.

Maintenance Mode

When your application is in maintenance mode, a custom view will be displayed for all incoming requests to your application. This makes it easy to "disable" your application while it is updating or when you are performing maintenance.

To enable maintenance mode, execute the down console command:

php console down

You may also provide a --secret option to bypass maintenance mode using a special bypass cookie:

php console down --secret="1630542a-246b-4b66-ab1d-dd9e9d837d3b"

To disable maintenance mode and bring the application back online, use the up command:

php console up