Symfony Dotenv

Symfony Dotenv parses .env files and populates PHP’s environment (via putenv, $_ENV, and $_SERVER) so applications can configure themselves from plain environment variables in development, without needing them set at the OS or web-server level. It supports variable interpolation, .env file overrides per environment (.env.local, .env.test), and includes a debug command for inspecting resolved values, and works standalone or as the environment layer inside a full Symfony application.

What You Get

• A Dotenv class that loads one or more .env files and populates $_ENV/$_SERVER/putenv()
• Support for the standard Symfony env-file override cascade (.env, .env.local, .env.$APP_ENV, .env.$APP_ENV.local)
• Variable interpolation (${OTHER_VAR}) and default-value syntax within .env files
• A DebugCommand and DotenvDumpCommand console command for inspecting which env vars are resolved and from which file
• Clear exception types (FormatException, PathException, VariableCircularReferenceException) for malformed or missing .env files

Common Use Cases

• Loading local development configuration (database URLs, API keys, debug flags) from a .env file instead of hardcoding or exporting shell variables
• Layering environment-specific overrides (.env.local, .env.test) on top of a checked-in base .env file
• Debugging which value an environment variable actually resolved to and from which file, via the bundled console command
• Using dotenv parsing standalone in non-Symfony PHP scripts or micro-frameworks that want the same .env convention

Under The Hood

Architecture — The component centers on a single Dotenv.php class that tokenizes and parses .env file contents (handling quoting, comments, interpolation, and export-style prefixes) and writes resolved values into PHP’s superglobals and process environment; Command/ layers optional Symfony Console commands (DebugCommand, DotenvDumpCommand) on top for introspection, and Exception/ defines a small hierarchy of typed parse/path errors. Tech Stack — Pure PHP (100% of the codebase), requiring PHP 8.4.1+, with symfony/console and symfony/process only as optional dev/require-dev dependencies for the CLI commands — the core parser has zero required dependencies. Code Quality — A dedicated Tests/ directory covers the parser and commands; the component ships explicit, typed exceptions (rather than generic RuntimeException) for format errors, missing paths, and circular variable references, which makes failure modes easy to catch and handle precisely. API Design — The primary entry point is a single method call ((new Dotenv())->load(...) or bootEnv(...)), matching the near-zero-config convention users expect from dotenv libraries across ecosystems; the override cascade (.env.local, .env.$APP_ENV) is opt-in and automatic once file naming conventions are followed.