PHP dotenv

Immutability determines whether Dotenv is allowed to overwrite existing environment variables.

• Immutable (Default): Use createImmutable(). It will not overwrite variables that are already set in the environment.
• Mutable: Use createMutable() if you want Dotenv to overwrite existing environment variables.

For advanced configurations, you can use the RepositoryBuilder to define specific adapters (like EnvConstAdapter or PutenvAdapter) and set immutability or an allow-list of variables.

// Example: Custom repository with specific adapters and immutability
$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\EnvConstAdapter::class)
    ->addWriter(Dotenv\Repository\Adapter\PutenvAdapter::class)
    ->immutable()
    ->make();

$dotenv = Dotenv\Dotenv::create($repository, __DIR__);
$dotenv->load();

// Example: Using an allow-list
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
    ->allowList(['FOO', 'BAR'])
    ->make();

$dotenv = Dotenv\Dotenv::create($repository, __DIR__);
$dotenv->load();

Upgrading to V5 requires PHP 7.1+. Key changes include:

1. getenv and putenv usage: Dotenv\Dotenv::createImmutable and Dotenv\Dotenv::createMutable no longer call getenv and putenv. If you need these functions, you must use Dotenv\Dotenv::createUnsafeImmutable or Dotenv\Dotenv::createUnsafeMutable.
2. Constructor changes: The Dotenv\Dotenv constructor now requires exactly 4 parameters (store, parser, loader, repository). It is recommended to continue using the static create* methods instead.
3. Repository Builder refactor: The RepositoryBuilder no longer includes default adapters. You must explicitly add readers and writers. Use createWithNoAdapters() to start from scratch or createWithDefaultAdapters() to start with defaults.
4. Adapter instantiation: You cannot construct adapters directly. Use their static create() method (which returns an Optional) or pass the class name to the builder to allow the library to handle system compatibility checks automatically.

// New way to build a repository in V5
$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\EnvConstAdapter::class)
    ->addWriter(Dotenv\Repository\Adapter\PutenvAdapter::class)
    ->make();

When upgrading from version 2 to version 3, several breaking changes in initialization and parsing must be addressed:

1. Initialization: Replace new Dotenv(...) with the static factory method Dotenv::create(...). The new constructor requires a Loader instance for customization.
2. Return Values: Loader::load() and its callers now return an associative array of the loaded variables (key => value) instead of an array of raw lines.
3. Value Trimming: The loader no longer automatically trims whitespace from parsed values.
4. Parsing Changes:
   • Comments: For unquoted strings, a # character is now treated as the start of a comment.
   • Multiline Support: Multiline quoted values are now supported.
   • Escaping: The parser is stricter regarding invalid escape sequences in quoted strings.
5. PHP Version: The minimum supported PHP version increased from 5.3.9 to 5.4.0.

Upgrading to V4 involves significant changes to how immutability is handled and how the library is initialized:

1. Immutability: Immutability is now decided at construction. Replace Dotenv::create with Dotenv::createImmutable for immutable loading, or Dotenv::createMutable for mutable loading. The overload() method has been removed; use createMutable and ->load() instead.
2. Variable Interpolation: Interpolation now runs right-to-left, allowing nested interpolations. You can also escape dollar signs ($) in unquoted or double-quoted strings to prevent interpolation.
3. Single Quoted Strings: Single quoted strings now behave like bash; they are treated literally and do not support character escaping.
4. Getting Variable Names: getEnvironmentVariableNames() is removed. Use array_keys($dotenv->load()) instead.
5. PHP Version: The minimum supported version is now PHP 5.5.9.

// V4 initialization pattern
use Dotenv\Dotenv;
use Dotenv\Repository\Adapter\EnvConstAdapter;
use Dotenv\Repository\Adapter\ServerConstAdapter;
use Dotenv\Repository\RepositoryBuilder;

$adapters = [
	new EnvConstAdapter(),
	new ServerConstAdapter(),
];

$repository = RepositoryBuilder::create()
    ->withReaders($adapters)
    ->withWriters($adapters)
    ->immutable()
    ->make();

Dotenv::create($repository, $path, null)->load();