Laravel Multienv Laravel Package

Getting Started

Add the package with Composer:

composer require allysonsilva/laravel-multienv

As of v2.1.0 the package requires Laravel 9.32+. On Laravel 8.x or an early 9.x release you must stay on the 2.0.x line — check composer.json constraints before upgrading an existing app.

The service provider is auto-discovered, so there is no manual registration on a modern Laravel skeleton. After install:

1. Keep a minimal root .env that only declares which environment you are in (typically APP_ENV).
2. Add sibling files named after that environment, e.g. .env.local, .env.staging, .env.production.
3. Run any Artisan command and confirm the resolved values with php artisan tinker → config('app.env') and app()->environmentFilePath().

Where to look first: the package's service provider in vendor/allysonsilva/laravel-multienv/src (it is what hooks the environment bootstrap), then the README's section on env-file naming/resolution order. If a multienv config file is publishable, publish and read it before you rely on defaults — the resolution order it defines is the whole behaviour of the package.

The first realistic use case is a single checkout that carries local, staging and production env files, switched purely by APP_ENV rather than by hand-editing .env before each deploy.

Implementation Patterns

Per-environment files in CI/CD. Let the pipeline/container set APP_ENV=staging, and ship .env.staging (or render it from your secret store at deploy time). The same image/commit then promotes cleanly from staging to production with only the environment variable changing.

One-off commands against another environment. Use the --env flag on Artisan to run a migration or a queue restart against a non-default environment without mutating the root .env. This is the highest-leverage day-to-day pattern — it removes the "edit .env, run command, remember to revert" dance.

Deploy scripts now use optimize. v2.1.0 adds support for php artisan optimize and optimize:clear, so your pipeline can use the single consolidated command (config + routes + events + views) instead of manually chaining config:cache, route:cache, etc. Recommended deploy order: pull code → optimize:clear → optimize. Build the cache on the target host, never commit it.

Local development. Point .env at local and keep real local values in .env.local, gitignored. Teammates clone, set APP_ENV=local, and are running without touching tracked files.

Testing. PHPUnit's <env> entries and real process environment variables still win over the dotenv files; keep test configuration in phpunit.xml so the multi-env resolution never interferes with the suite.

Gotchas and Tips

• The 9.32 minimum is the real upgrade risk. It arrived in a minor release (2.1.0), so a loose ^2.0 constraint will silently pull it in and break installs on older Laravel. Pin ^2.0 only if you are already on 9.32+, otherwise pin 2.0.*.
• optimize support is new — upgrade before relying on it. On 2.0.x, php artisan optimize (which internally caches config) can produce a cache built from the wrong env file, or fail outright. If your deploy already calls optimize, treat 2.1.0 as required, not optional.
• Cached config freezes the resolved environment. A bootstrap/cache/config.php built for production will keep pointing at production values even after APP_ENV changes. Always optimize:clear (or config:clear) when switching environments on a shared host, and never share a cache directory between environments.
• The root .env still has to exist and declare the selector variable. Missing or malformed root .env is the most common cause of "it loaded the wrong file" — verify with app()->environmentFilePath() rather than guessing.
• Process env beats dotenv. Variables exported in the shell (or injected by the container/Forge) generally take precedence over the files, which is exactly what you want in production but can confuse local debugging when a stale exported APP_ENV lingers in your terminal session.
• Not a secrets manager. The package only selects which file is read; file permissions, encryption at rest, and rotation remain yours. Keep .env* out of git except .env.example.
• Extension point: if resolution needs to be hostname- or path-based rather than variable-based, subclass the provider's resolver or publish/override the config rather than editing vendor/. Keep the override in app/Providers so it survives composer update.