Laravel production configuration: environment and cached config

Who this is for: Laravel developers preparing an application for a staging or production environment.

What you will learn: how environment variables feed Laravel configuration, how configuration caching changes when those values are read, and which deployment checks to make without exposing secrets.

Prerequisites: Basic Laravel configuration and command-line familiarity. This is a safe workflow overview, not a server-specific deployment recipe.

Tested environment: Laravel Framework 13.16.1 and PHP 8.4.15. TeachyLeaf's test configuration uses SQLite in memory and does not reproduce its production server configuration.

Separate application code from environment settings

The same application code may run locally, in tests, and in production, but each environment needs different settings: its URL, database connection, mail transport, cache, session behavior, and debug mode. Laravel reads environment values into configuration files, where application code should access them through Laravel's config() helper.

TeachyLeaf's .env.example is a development-oriented template: it includes local defaults such as APP_ENV=local, APP_DEBUG=true, SQLite, and the log mailer. Those values are not production recommendations. Do not copy the example to production unchanged.

Keep secrets out of the repository

The real .env file is excluded by this project's .gitignore. Production values should be supplied through the hosting platform's protected environment configuration or another private secret-management mechanism—not committed to Git, pasted into public logs, or included in an article.

For a production application, check that the deployed configuration sets an appropriate environment, disables detailed debug output, uses the intended site URL and service connections, and keeps secret values private. In particular, APP_DEBUG should be false for a public production site so unexpected errors do not reveal stack traces and internal details.

Never replace an existing production application key casually. Changing APP_KEY can invalidate encrypted application data and sessions; treat it as a sensitive, planned operation.

Read environment values through configuration

Laravel convention is to call env() inside configuration files, and use config() from application code. For example, TeachyLeaf defines an asset-version setting in config/assets.php:

// config/assets.php
return [
    'version' => env('ASSET_VERSION', '1'),
];

Then application code can read the resolved setting with:

$version = config('assets.version');

This distinction matters after configuration is cached: Laravel does not load the .env file in the same way for requests, so calls to env() outside configuration files can return unexpected values. Put the environment lookup in a configuration file and read the setting from that configuration elsewhere.

Understand configuration caching

For a deployment, Laravel can combine configuration files into a cache so the framework does not need to load each file separately on every request:

php artisan config:cache

After configuration has been cached, changing the environment settings alone does not refresh the cached values. Rebuild the configuration cache as part of the deployment process after the correct environment values are available. To remove the configuration cache during controlled troubleshooting, Laravel provides:

php artisan config:clear

Run cache commands in the correct application directory and environment. Do not print or paste the full environment file or a dump of all configuration when troubleshooting: output can contain credentials. Verify only the specific non-secret setting or behavior you need to check.

Plan database and maintenance operations separately

If a release includes database migrations, first verify the target connection, migration plan, backup and recovery approach, and application compatibility. Laravel requires an explicit confirmation flag for migrations in production:

php artisan migrate --force

The flag permits the command to run without an interactive confirmation; it does not make a migration safe or create a backup. Use it only as part of a reviewed deployment procedure for the intended database.

Maintenance mode can be useful during a planned operation, but it affects visitor access. Coordinate its use with the deployment process and verify the site returns to service afterward. Do not treat maintenance mode as a substitute for backups, health checks, or an application rollback plan.

Use a deployment checklist

1. Supply the production environment values through a protected deployment mechanism; do not commit secrets.
2. Confirm the environment, public URL, debug setting, database, cache, session, and mail configuration are appropriate for the target.
3. Deploy the application code and dependencies using the site's established release process.
4. Build or refresh cached configuration only after the correct environment values are available.
5. Review any migration against the target database and an appropriate backup and recovery plan before applying it.
6. Check health, logs, contact delivery, and important public pages without exposing credentials or personal data.

Exact commands and ordering depend on the host, release strategy, and services in use. Follow the provider's instructions and test the procedure in staging when available; this lesson does not claim that one command sequence fits every server.

Practice: spot the unsafe defaults

A developer copies a local example file into a public production deployment unchanged. It contains APP_ENV=local and APP_DEBUG=true. What should they do before exposing the application?

References

• Laravel 13 configuration
• Laravel 13 deployment
• Laravel 13 production migrations