Dotenv files cascade override (.env.local, .env.testing, .env.testing.local)

[antonkomarev]

Currently, Laravel relies primarily on a single .env file (and potentially a specific .env.testing for tests). This file is typically git-ignored, requiring developers to manually copy .env.example to .env upon setting up the project.

While functional, this approach lacks granularity. Changes to configuration defaults require every developer to manually update their ignored .env files. Furthermore, overriding specific testing configurations locally often leads to accidental modifications of shared files or requires complex CI/CD scripting to swap files.

Adopting the Symfony-style cascading configuration (using .env, .env.local, .env.[environment], .env.[environment].local) would significantly improve Developer Experience (DX) and deployment workflows.

Current package supports this feature:

• Additional .env files are not loaded vlucas/phpdotenv#521

Key benefit: Separation of Secrets and Config

Usage: Secrets (API keys, DB passwords) go into .env.local, which is git-ignored. Defaults go into .env.

Benefit: This cleanly separates configuration structure (tracked in Git) from sensitive credentials (kept local), reducing the risk of accidentally committing secrets.

Sidenotes

In Symfony test environments ignores .env.local file, but other environments use it as well.

Example:

• [testing] .env -> .env.testing -> .env.testing.local
• [staging] .env -> .env.local -> .env.testing -> .env.testing.local

How it might look like

.env (commited to repo)

APP_NAME=super-app

DB_CONNECTION=pgsql

.env.local (git ignored)

APP_ENV=stage

.env.stage.local (git ignored)

APP_ENV=stage

DB_HOST=stage-super-app-db.example.com
DB_DATABASE=super_app_db
DB_USERNAME=stage_user
DB_PASSWORD=stage_password
DB_PORT=5432

.env.test.local (git ignored)

APP_ENV=test

DB_HOST=postgres18
DB_DATABASE=test_super_app_db
DB_USERNAME=root
DB_PASSWORD=secret
DB_PORT=15432

Compiled at runtime .env will look like:

APP_NAME=super-app
APP_ENV=stage

DB_CONNECTION=pgsql
DB_HOST=stage-super-app-db.example.com
DB_DATABASE=super_app_db
DB_USERNAME=stage_user
DB_PASSWORD=stage_password
DB_PORT=5432