Configuration

Laravel reads configuration from two places: the files in config and the environment file at the project root. Environment values make one codebase behave differently on a laptop, a staging server, and production without editing tracked files.

The environment file

.env contains key-value pairs. Values with spaces or special characters should be quoted. The file is ignored by Git, while .env.example documents the keys a teammate needs.

APP_NAME=Acme
APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.com

LOG_CHANNEL=stack
LOG_LEVEL=warning

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=acme
DB_USERNAME=acme
DB_PASSWORD="a long secret"

Reading values

Call env() only inside configuration files. Application code should use the config() helper so that cached configuration and default values work correctly.

// config/services.php
return [
    'reports' => [
        'endpoint' => env('REPORTS_ENDPOINT', 'https://reports.example.com'),
        'timeout'  => (int) env('REPORTS_TIMEOUT', 5),
    ],
];

// anywhere in the application
$endpoint = config('services.reports.endpoint');

Configuration caching

In production, run php artisan config:cache to merge every configuration file into one cached file. This avoids reading and merging files on each request. After caching, env() returns null outside configuration files, which is another reason to route environment values through config.

php artisan config:cache
php artisan config:clear
php artisan optimize:clear

Environment detection

app()->environment() reports the current environment. Use it for behavior that truly depends on the environment, such as enabling verbose logging locally, rather than sprinkling conditionals through controllers.

if (app()->environment('local')) {
    // enable debug-only tooling
}

Settings that often need attention

• APP_KEY encrypts cookies, sessions, and serialized data; keep it stable after deployment.
• APP_DEBUG must be false in production so stack traces are not shown to visitors.
• APP_URL affects URL generation when no request context exists, such as in queued jobs.
• Mail, queue, cache, and session drivers differ between local development and production; review them before launch.
• Time zone can be set in config/app.php and should match how you store timestamps.