Phpdotenv Laravel Package

Getting Started

Start by installing the package via Composer:

composer require vlucas/phpdotenv

Then create a .env file in your project root (outside version control) with key-value pairs:

APP_ENV=local
DB_HOST=localhost
DB_PASSWORD=supersecret

Also create a .env.example file (checked into VCS) with placeholders to guide collaborators.
Load env vars early in your app’s lifecycle:

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

Access variables via $_ENV['KEY'], $_SERVER['KEY'], or (with createUnsafeImmutable) getenv('KEY').

Implementation Patterns

• Laravel Integration: Laravel ships with DotEnv preconfigured in bootstrap/app.php. Use config() with env() behind the scenes — but avoid calling env() outside config files (it may be cached/undefined in production).
• Validation on Load: Enforce required/typed vars immediately after load():

  $dotenv->required(['APP_KEY', 'DB_HOST'])->notEmpty()->isString();
  $dotenv->required('APP_DEBUG')->isBoolean();
  

• Per-Environment Configs: Switch between .env.local, .env.staging, etc. by passing filename:

  $dotenv = Dotenv\Dotenv::createImmutable(__DIR__, $_ENV['APP_ENV_FILE'] ?? '.env');
  $dotenv->load();
  

• Repository Customization: For advanced control (e.g., strict immutability, allow-listing):

  $repo = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
      ->immutable()
      ->allowList(['APP_', 'DB_'])
      ->make();
  $dotenv = Dotenv\Dotenv::create($repo, __DIR__)->load();
  

• Testing: Use .env.testing or override in tests by calling createMutable() before loading.

Gotchas and Tips

• Immutability Matters: createImmutable() (default) refuses to overwrite existing env vars (e.g., set via Apache/Nginx). Use createMutable() only if you must override system vars — but be cautious for security.
• getenv() vs Superglobals: Superglobals ($_ENV, $_SERVER) are populated during load; getenv() reflects current state. For CLI scripts, prefer superglobals (they’re populated reliably).
• PHP Compatibility: Ensure variables_order in php.ini includes E and S (e.g., variables_order = "EGPCS"); otherwise $_ENV/$_SERVER may be empty.
• Multi-line Values: Only quote values containing spaces or special chars — avoid unquoted values starting with # or =. Nested vars (${FOO}) are resolved at parse time.
• Production Caution: .env is for development/local setups. In production, prefer native env vars (set by process manager, container, or cloud platform) — don’t deploy .env files.
• Validation Pitfalls: isInteger() expects an integer string (e.g., "123"), not floats like "12.0". Use isNumeric() for floats/ints.
• Security: .env should be in .gitignore. Never commit secrets. Use .env.example + documentation to guide onboarding.
• Debugging: To inspect parsed vars without loading:

  $vars = Dotenv\Dotenv::parse(file_get_contents(__DIR__.'/.env'));