Configuration

Learn about Laravel configuration files, environment variables (.env), how to access configuration values, caching, debug mode, and maintenance mode.

Introduction

All of the Laravel framework’s configuration files are stored in the config/ directory. Each option is documented with comments, so open the files and take a look at the available options.

Configuration files manage a variety of core settings such as database connection information, mail server information, application URL, and encryption keys.

The about command

Use the about Artisan command to see an overview of your application’s configuration, drivers, and environment.

php artisan about

To check only a specific section, use the --only option.

php artisan about --only=environment

To inspect the values of a specific configuration file in detail, config:show is handy.

php artisan config:show database

Environment configuration (.env)

It’s common to want configuration values to differ based on the environment your application is running in. For example, you may want to use a different cache driver locally than in production.

Laravel makes this easy by leveraging the DotEnv PHP library. On a fresh installation, the root directory contains a .env.example file with common environment variables, and it’s automatically copied to .env during installation.

When developing as a team, it’s convenient to keep the .env.example file up to date and commit it to the repository. Setting placeholder values makes it clear to other developers on the team which environment variables they need.

Environment file security

Do not commit the .env file to source control. Different developers and servers may need different configurations, and including it in the repository risks exposing sensitive information if an incident occurs.

However, Laravel has a built-in feature for encrypting your environment file, which allows you to safely commit it to source control in an encrypted form.

Additional environment files

When starting up, Laravel checks whether the APP_ENV environment variable or the CLI --env argument is set. If it is, and a .env.[APP_ENV] file exists, Laravel loads it. Otherwise, the default .env file is used.

Environment variable types

All variables in your .env file are parsed as strings, but the following special values are provided so env() can return a broader set of types.

.env value	Value returned by env()
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) ''
(empty)	(string) ''
null	(null) null
(null)	(null) null

To define a value that contains a space, wrap it in double quotes.

APP_NAME="My Application"

Retrieving environment variables

All the variables listed in your .env file are loaded into the PHP $_ENV super-global when a request is received. Inside configuration files, use the env() function to retrieve values.

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

The second argument is the default value, which is returned if the environment variable does not exist.

Determining the current environment

The current environment is determined by the APP_ENV variable in your .env file. You can retrieve it via the environment method on the App facade.

use Illuminate\Support\Facades\App;

$environment = App::environment();

You can also pass an argument to check whether the application is in a given environment.

if (App::environment('local')) {
    // Local environment
}

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

Encrypting environment files

Unencrypted environment files should not be stored in source control, but Laravel provides functionality to encrypt them.

php artisan env:encrypt

When run, .env is encrypted and the encrypted contents are saved to a .env.encrypted file. The decryption key is printed in the command’s output, so store it in a secure password manager.

To decrypt, use the env:decrypt command.

php artisan env:decrypt

Accessing configuration values

You can access configuration values from anywhere in your application using the Config facade or the global config() function. Use “dot” notation to combine the file name and the option name.

use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

// The global helper works too
$value = config('app.timezone');

// Specify a default value if the setting is not present
$value = config('app.timezone', 'Asia/Tokyo');

To change a value at runtime, use Config::set() or pass an array to config().

Config::set('app.timezone', 'America/Chicago');

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

Typed retrieval methods are also available. If the types don’t match, an exception is thrown.

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');

Caching configuration

To improve your application’s performance, cache all configuration files into a single file.

php artisan config:cache

This command combines all configuration options into a single file so the framework can load them quickly.

Run config:cache as part of your production deployment process. Do not run it during local development, since configuration changes frequently there.

Once the cache is created, the .env file is no longer loaded during framework requests or Artisan command execution. That means env() returns only system-level environment variables.

For that reason, always call the env() function only from configuration files in the config/ directory. Elsewhere in your application, use config() to retrieve configuration values.

To remove the cache, use the config:clear command.

php artisan config:clear

Publishing configuration files

Most of Laravel’s configuration files are already published in the config/ directory, but some files like cors.php and view.php are not published by default.

Use the config:publish command to publish unpublished configuration files.

php artisan config:publish

php artisan config:publish --all

Debug mode

The debug option in config/app.php determines how much error information is actually shown to the user. By default, this option follows the value of the APP_DEBUG environment variable in your .env file.

In production, always set APP_DEBUG to false. Leaving it true risks exposing sensitive configuration values to end users.

# Local development
APP_DEBUG=true

# Production
APP_DEBUG=false

Maintenance mode

When your application is in maintenance mode, a custom view is displayed for all requests. This makes it easy to “disable” your application temporarily while it is updating or when you’re performing maintenance.

Enabling maintenance mode

php artisan down

If you pass the --refresh option, the browser will automatically reload after the specified number of seconds.

php artisan down --refresh=15

The --retry option is set as the value of the Retry-After HTTP header.

php artisan down --retry=60

Bypassing maintenance mode

To allow only specific users to access using a secret token, use the --secret option.

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

Use the --with-secret option to have Laravel generate a token for you.

php artisan down --with-secret

Maintenance mode across multiple servers

By default, Laravel manages maintenance mode via a file. For a multi-server setup, a cache-based approach is more convenient.

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

Pre-rendering the maintenance view

If you run php artisan down during a deployment, users who access your application while dependencies are being updated may see errors. To avoid this, pre-render the view with the --render option.

php artisan down --render="errors::503"

You can also redirect all requests to a specific URL during maintenance mode.

php artisan down --redirect=/

Disabling maintenance mode

php artisan up

You can customize the default maintenance mode template by creating resources/views/errors/503.blade.php.

If you want zero downtime, consider using a fully managed platform like Laravel Cloud.

Next steps

Routing

Learn the basics of routing that connects URLs to controllers.