symfony/dotenv: loading .env files into PHP's $_ENV and $_SERVER

The gap symfony/dotenv fills in a plain PHP project

PHP gives you $_ENV and $_SERVER, but nothing reads a .env file for you. On a shared host, in a small CLI script, or in a test bootstrap, there is often no process manager setting variables before PHP starts. The usual workaround is a hand-written parser or a hardcoded config array, and both drift.

symfony/dotenv is the component that closes that gap. It parses a .env file and makes the values available through $_SERVER or $_ENV, which is exactly the promise in the README. It is published as a standalone Composer package, so you do not need symfony/framework-bundle or the full framework to use it. That matters: the component ships in the same repository as Symfony but is installable on its own.

The audience is narrow and specific. If you already run PHP under Docker, Kubernetes, or a systemd unit that injects variables, you may not need this at all. If your configuration lives in a .env file that a developer copies from .env.dist and edits locally, this is the piece that turns that file into runtime state.

How load, overload and loadEnv differ in precedence

The component is a parser plus a set of loaders. The README shows four entry points, and the difference between them is what happens when a variable already exists.

load() reads one or more files and sets variables. If the key is already present in $_ENV or $_SERVER, load() leaves it alone. That is the behaviour you want in production, where the real environment should win over a file that may be stale. overload() is the opposite: it writes over existing values. The README describes it as overwriting existing env variables, and that is a deliberate, dangerous choice you should reserve for local development or test bootstrapping.

loadEnv() is the higher-level helper. The README says it loads .env, .env.local, and .env.$APP_ENV.local or .env.$APP_ENV. So the file set is computed from an APP_ENV value rather than listed by hand. This is the convenience layer, and it is also where surprises live: the order in which those files are merged decides which value wins, and the README does not spell that order out beyond naming the files. If you depend on loadEnv(), read the component's tests before you rely on a particular override in a staging environment.

The repository layout supports this reading. Dotenv.php sits at the top level next to a Command/ directory and an Exception/ directory, so there is a console command and a dedicated exception type in the package, not just a single class.

Installing symfony/dotenv and loading a first file

Installation is one Composer command. The README gives it directly:

composer require symfony/dotenv

Create a .env file in your project root. The README's example format is a single assignment:

YOUR_VARIABLE_NAME=my-string

Then load it from PHP and read the value back. The README shows both access paths:

use Symfony\Component\Dotenv\Dotenv;

$dotenv = new Dotenv();
$dotenv->load(__DIR__.'/.env');

// Usage with $_ENV
$envVariable = $_ENV['YOUR_VARIABLE_NAME'];

// Usage with $_SERVER
$envVariable = $_SERVER['YOUR_VARIABLE_NAME'];

After this, $envVariable holds the string my-string. If you load several files in one call, the README's example is $dotenv->load(__DIR__.'/.env', __DIR__.'/.env.dev'); and the same rule applies: values already present are not replaced. To force replacement, call overload() instead, as in $dotenv->overload(__DIR__.'/.env');. For the conventional Symfony file set, call $dotenv->loadEnv(__DIR__.'/.env'); and let the component decide which of .env, .env.local and the environment-specific files to read.

Where symfony/dotenv is the wrong tool

The component only fills variables that are not already set, unless you call overload(). That single design decision breaks the most common deployment story people expect from a .env library.

If your container or your hosting panel injects environment variables before PHP runs, load() will read your .env file, parse it, and then discard every value that collides with the real environment. Nothing warns you. You get the injected value, which is usually correct, but it means a .env file left in the image is dead weight and can mislead the next developer who edits it expecting an effect. overload() fixes the symptom and creates a worse problem: a stale file in the image silently wins over the orchestrator's configuration.

There is also the question the search data keeps asking, whether dotenv is still needed. For a PHP process that already receives a complete environment, the honest answer is that this component adds a parser and a file convention you do not need. The component is not a secrets manager, it does not encrypt anything, and it does not validate that a required key exists. A missing variable shows up later as an undefined index or a null, not as a startup error from this package.

Finally, the .env file itself is a deployment artifact. The README does not document rollback, file watching, or cache invalidation, so if you expect the component to notice an edited .env mid-process, it will not.

How it compares to vlucas/phpdotenv

The obvious alternative in PHP is vlucas/phpdotenv, the package most PHP projects reached for before Symfony shipped its own. The two solve the same problem with different defaults and different scopes.

vlucas/phpdotenv is framework-agnostic by construction and has no companion console command; you call its loader and you are done. symfony/dotenv is a Symfony component, which shows in the repository layout: there is a Command/ directory, so a console command ships with the package, and there is an Exception/ directory for typed failures. If you already use Symfony's console, that integration is the reason to pick this one.

The precedence model also differs in emphasis. symfony/dotenv makes the non-overwriting default explicit in its API by giving you a separate overload() method, and it adds loadEnv() as a convention for the .env, .env.local, .env.$APP_ENV chain. If you do not want a framework's file naming convention imposed on your project, that helper is extra surface you will not use, and the plain load() call is all you need from either package.

Editorial conclusion

Adopt symfony/dotenv if you write PHP and want .env values in $_ENV or $_SERVER without pulling in a framework. Skip it if your runtime already injects real environment variables, since load() will not overwrite them and the file becomes decoration. Before committing to it, read the precedence rules in the component's own tests and confirm which of load(), overload() and loadEnv() matches your deployment, because the three behave differently when a variable already exists.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. symfony/dotenv on GitHub