Laravel Configuration Files and Environment Settings Guide

Introduction

All configuration files of the Laravel framework are stored in the config directory. Each option is documented, allowing you to inspect the files and become familiar with the available configuration settings.

Environment Configuration

Different environments often require different settings, such as using a different cache driver locally versus in production. Laravel uses Vance Lucas's PHP library DotEnv to simplify this. A fresh Laravel installation includes a .env.example file, which Composer renames to .env. If you installed Laravel manually, you must rename the file yourself.

The .env file should never be committed to source control because each developer or server may need a distinct environment configuration, and exposing it could leak sensitive credentials.

In team development you may keep a .env.example file with placeholder values so others can see required variables. You can also create a .env.testing file that overrides .env when running PHPUnit tests with the --env=testing option.

Tip: All variables in the .env file can be overridden by external environment variables (e.g., server‑level or system‑level).

Environment Variable Types

Values in the .env file are parsed as strings, but Laravel reserves certain values that the env() helper converts to other types: .env value env() value

true

(bool) true

(true)

(bool) true

false

(bool) false

(false)

(bool) false

empty

(string) ''

(empty)

(string) ''

null

(null) null

(null)

(null) null

To include spaces in a value, wrap it in double quotes, e.g.:

APP_NAME="My Application"

Retrieving Environment Configuration

When a request is handled, all variables defined in .env are loaded into PHP's super‑global $_ENV. You can retrieve them with the env function, optionally providing a default value:

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

Determining the Current Environment

The current environment is defined by the APP_ENV variable in .env. You can access it via the App facade: $environment = App::environment(); You may also pass one or more values to environment() to check if the current environment matches any of them:

if (App::environment('local')) {
    // current environment is local
}

if (App::environment(['local', 'staging'])) {
    // current environment is local or staging
}

Tip: The server‑level APP_ENV variable overrides the value in .env , which is useful for configuring the same codebase for different hosts.

Hiding Environment Variables on Debug Pages

When an uncaught exception occurs and APP_DEBUG is true, the debug page shows all environment variables. To hide sensitive variables, add them to the debug_blacklist option in config/app.php:

return [
    // ...
    'debug_blacklist' => [
        '_ENV' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],
        '_SERVER' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],
        '_POST' => [
            'password',
        ],
    ],
];

Accessing Configuration Values

You can retrieve configuration values anywhere in your application using the global config helper with "dot" syntax. A default value can be supplied if the key does not exist: $value = config('app.timezone'); To set configuration values at runtime, pass an associative array to config:

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

Configuration Caching

For better performance, run the Artisan command config:cache to combine all configuration files into a single cached file that Laravel loads quickly.

Typically you execute php artisan config:cache as part of your production deployment. Do not run this command in a local development environment because configuration files are frequently changed during development.

Note: When the configuration is cached, the .env file is no longer loaded, and any call to env() will return null . Ensure that only configuration files call env() before caching.

Maintenance Mode

When the application is in maintenance mode, all incoming requests receive a custom view and a

503

MaintenanceModeException

is thrown.

Enable maintenance mode with: php artisan down You can provide a custom message and retry timeout:

php artisan down --message="Upgrading Database" --retry=60

Specific IP addresses or networks can be allowed to bypass maintenance mode:

php artisan down --allow=127.0.0.1 --allow=192.168.0.0/16

Disable maintenance mode with:

php artisan up

Tip: Customize the default maintenance view by editing resources/views/errors/503.blade.php .