Laravel env() Outside config/: Catch Deployment Bugs Before config:cache
The bug only appears after configuration caching A Laravel application can behave perfectly during development and then fail after deployment because a service class reads an environment variable directly: // app/Services/AcmeClient.php $token = env ( 'ACME_TOKEN' ); Laravel's configuration cache changes the boot process. Once configuration has been cached, the framework does not load the…
After configuration caching, a Laravel application may perform normally during development but fail during deployment due to a service class reading an environment variable directly, as shown in this code snippet from app/Services/AcmeClient.php: $token = env('ACME_TOKEN'); When the Laravel configuration cache alters the boot process, it no longer loads the application's .env file for regular requests or Artisan commands.
Consequently, a direct env() call outside a configuration file may only return an external system value or its fallback value. To resolve this issue, developers should read the environment variable once from a configuration file. In config/services.php, this approach is demonstrated by defining an 'acme' array with a 'token' entry that reads env('ACME_TOKEN'): return [ 'acme' => [ 'token' => env('ACME_TOKEN'), ], ]; This primary fix aims to prevent the bug.
However, developers must also address environment drift, which occurs even when all env() calls are correctly placed. A project might contain multiple .env files, such as .env, .env.testing, .env.production, and .env.sample, each with different environment variables. For example, the .env file may contain APP_NAME=Codegenie ACME_TOKEN=local-secret, while the .env.production file includes APP_NAME=Codegenie.
As these values will differ, missing ACME_TOKEN key indicates an incomplete deployment contract. Other potential issues include duplicate keys, case-sensitive discrepancies, unused keys, and direct getenv() or $_ENV access. To minimize failures, a small manual review can be performed. This review recommends searching application-owned PHP files for env() calls and moving valid reads to config/, comparing key inventories of environment files, and checking phpunit.xml and .env.testing together.
Additionally, developers should review Vite import.meta.env and loadEnv() usage. Running the application with configuration cached before deployment is also recommended. Laravel Env Guard, a tool created by the author to automate this review process, can be installed as a development dependency using Composer. It scans application files for unsafe env() and Illuminate\Support\Env::get() calls outside config/, direct raw environment access, duplicate or case-mismatched keys, and drift across .env files.
By default, Laravel Env Guard runs during local console boots and does not require a separate audit command. The tool blocks findings by default, writing warnings and errors to STDERR during Artisan commands. Laravel Env Guard does not handle secrets, perform telemetry, or modify .env files. It intentionally excludes encrypted environment files, as auditing them requires decryption.
The package is a development guard, not a secret manager or deployment system. The current release, v1.2.1, supports Laravel 12 and 13 across PHP 8.2–8.5 combinations.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
