> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```mermaid theme={null}
flowchart LR
    A[".env file"] -->|env()| B["config/ files"]
    B -->|config()| C["Application"]
```

### The `about` command

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

```shell theme={null}
php artisan about
```

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

```shell theme={null}
php artisan about --only=environment
```

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

```shell theme={null}
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](https://github.com/vlucas/phpdotenv) 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.

<Info>
  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.
</Info>

### Environment file security

<Warning>
  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.
</Warning>

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.

```ini theme={null}
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.

```php theme={null}
'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.

```php theme={null}
use Illuminate\Support\Facades\App;

$environment = App::environment();
```

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

```php theme={null}
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.

```shell theme={null}
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.

```shell theme={null}
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.

```php theme={null}
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()`.

```php theme={null}
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.

```php theme={null}
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.

```shell theme={null}
php artisan config:cache
```

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

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

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.

<Tip>
  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.
</Tip>

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

```shell theme={null}
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.

```shell theme={null}
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.

<Warning>
  **In production, always set `APP_DEBUG` to `false`.** Leaving it `true` risks exposing sensitive configuration values to end users.
</Warning>

```ini theme={null}
# 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

```shell theme={null}
php artisan down
```

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

```shell theme={null}
php artisan down --refresh=15
```

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

```shell theme={null}
php artisan down --retry=60
```

### Bypassing maintenance mode

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

```shell theme={null}
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
```

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

```shell theme={null}
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.

```ini theme={null}
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.

```shell theme={null}
php artisan down --render="errors::503"
```

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

```shell theme={null}
php artisan down --redirect=/
```

### Disabling maintenance mode

```shell theme={null}
php artisan up
```

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

<Tip>
  If you want zero downtime, consider using a fully managed platform like [Laravel Cloud](https://cloud.laravel.com).
</Tip>

## Next steps

<Card title="Routing" icon="route" href="/en/routing">
  Learn the basics of routing that connects URLs to controllers.
</Card>


## Related topics

- [Database configuration](/en/database.md)
- [Hashing](/en/hashing.md)
- [Mail](/en/mail.md)
- [Logging](/en/logging.md)
- [Cache](/en/cache.md)