Originally published on laravel.learnio.dev — part of the Laravel best practices course. View this lesson on the original site.

Configure Laravel per environment

Laravel separates configuration by environment so local, staging, and production can run the same code with different values.

The three config layers you should know

  1. .env file for environment-specific values.
  2. config/*.php files for framework and app configuration.
  3. runtime config cache for production performance.

Use env() inside config files, not directly in application logic.

Typical .env values to check first

  • APP_ENV: the current environment name (for example local, staging, production). Teams use this to control environment-specific behavior.
  • APP_DEBUG: whether detailed error output is shown. Keep this true locally and false in production.
  • APP_URL: the base URL Laravel uses for generated links and some framework features.
  • APP_KEY: the application encryption key used for encrypted data, signed cookies, and session security.
  • DB_CONNECTION: which database driver Laravel should use (mysql, pgsql, sqlite, etc.).
  • DB_HOST: hostname or IP address of your database server.
  • DB_PORT: network port for the database service (for example 3306 for MySQL).
  • DB_DATABASE: database name Laravel should connect to.
  • DB_USERNAME: database user account.
  • DB_PASSWORD: password for that database user.

If these are wrong, many features fail in confusing ways.

How values flow

flowchart LR
  A["Environment values"] --> B["Config files"]
  B --> C["config reads in app code"]
  C --> D[Runtime behavior]

Useful commands while developing

php artisan config:clear
php artisan cache:clear
php artisan config:cache
  • config:clear removes cached config (useful after .env changes).
  • config:cache is a production-oriented optimization step.

Optional: switching environment profiles quickly

If you frequently switch between local/staging-style .env setups during development, you can use devkit/env-profiles to save and apply named profiles from the project root.

Example workflow:

composer require --dev devkit/env-profiles
./vendor/bin/devkit-env save local
./vendor/bin/devkit-env save staging --from .env.staging
./vendor/bin/devkit-env use staging

This is optional, but it helps reduce manual .env editing mistakes when switching contexts.

Practical checklist

When environment-related behavior looks wrong:

  1. Confirm .env values.
  2. Confirm related config/*.php mapping.
  3. Clear config cache.
  4. Re-test the failing path.

Keeping this sequence prevents hours of debugging phantom config issues.

From Laravel best practices — What is Laravel?