PHP dotenv

https://github.com/vlucas/phpdotenv
Admin
PHP dotenv is a PHP library, installed with Composer, that loads variables from .env files into...
Tokens:51,435
Snippets:412
Trust Score:10
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example .env.example file

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Example .env.example file with dummy values. Commit this file to the project so collaborators know which variables are required.

```shell
S3_BUCKET="devbucket"
SECRET_KEY="abc123"
```

--------------------------------

### StoreBuilder usage examples

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

Two examples: one equivalent to Dotenv::createImmutable's internal store, and one with custom names/encodings and merging across several files.

```php
// Equivalent to Dotenv::createImmutable's internal store: .env in one path
$store = Dotenv\Store\StoreBuilder::createWithDefaultName()
    ->addPath(__DIR__)
    ->shortCircuit()
    ->make();
```

```php
// Custom names/encodings and merging across several files:
$store = Dotenv\Store\StoreBuilder::createWithNoNames()
    ->addPath('/srv/app')
    ->addPath('/srv/app/config')
    ->addName('.env')
    ->addName('.env.local')
    ->fileEncoding('UTF-8')
    ->make();
$content = $store->read();
```

--------------------------------

### Example .env file

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Example .env file with sensitive values. Keep this file out of version control and add it to .gitignore.

```shell
S3_BUCKET="dotenv"
SECRET_KEY="souper_seekret_key"
```

--------------------------------

### AdapterRepository usage example

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Repository.md

Usage example for AdapterRepository. Shows set, get, has, and clear returning expected values, and that get('') throws InvalidArgumentException with the message "Expected name to be a non-empty string."

```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()->make();
$repository->set('FOO', 'Bar'); // true
$repository->get('FOO');        // 'Bar'
$repository->has('FOO');        // true
$repository->clear('FOO');      // true
try {
    $repository->get('');       // InvalidArgumentException
} catch (InvalidArgumentException $e) {
    // "Expected name to be a non-empty string."
}
```

--------------------------------

### Lines::process() usage example

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Parser-Value.md

Example of Lines::process() joining multiline values and removing comments.

```php
$entries = Dotenv\Parser\Lines::process(['FOO="Hello', 'World"', '# comment', 'BAR=1']);
// ['FOO="Hello\nWorld"', 'BAR=1']
```

--------------------------------

### Create an array-backed repository with ArrayAdapter

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Adapters.md

Builds a repository using only the ArrayAdapter, so reads and writes stay in memory and never touch the OS environment. The example sets 'FOO' to 'Bar' and then reads it back, returning 'Bar'.

```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\ArrayAdapter::class)
    ->make();
$repository->set('FOO', 'Bar');
$repository->get('FOO'); // 'Bar' — the OS environment is untouched
```

--------------------------------

### Creating a Dotenv instance with custom collaborators

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Example of instantiating Dotenv\Dotenv with a StringStore, Parser, Loader, and a repository built with ArrayAdapter. The load() method returns an array of variables, e.g., ['FOO' => 'Bar'].

```php
$dotenv = new Dotenv\Dotenv(
    new Dotenv\Store\StringStore("FOO=Bar"),
    new Dotenv\Parser\Parser(),
    new Dotenv\Loader\Loader(),
    Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
        ->addAdapter(Dotenv\Repository\Adapter\ArrayAdapter::class)
        ->make()
);
$vars = $dotenv->load(); // ['FOO' => 'Bar']
```

--------------------------------

### V4 example: Create immutable repository and load environment

Source: https://github.com/vlucas/phpdotenv/blob/master/UPGRADING.md

Shows the new way to initialize Dotenv in V4, using RepositoryBuilder with adapters and immutable() to create a repository, then passing it to Dotenv::create. This replaces the old Dotenv::create usage.

```php
<?php

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();
```

--------------------------------

### Value usage example - append and create

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Parser-Value.md

Demonstrates building a Value with append() and create(), and shows that getVars() returns offsets in descending order.

```php
$value = Dotenv\Parser\Value::blank()->append('Hello ', false)->append('${NAME}', true);
$value->getChars(); // 'Hello ${NAME}'
$value->getVars();  // [6]

$value2 = Dotenv\Parser\Value::create('a${B}c${D}', [1, 5]);
$value2->getVars(); // [5, 1] — descending copy
```

--------------------------------

### Install phpdotenv with Composer

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Install the vlucas/phpdotenv package via Composer.

```bash
composer require vlucas/phpdotenv
```

--------------------------------

### create() with custom repository

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv-Create.md

Creates a Dotenv instance with a custom repository. The repository is built with RepositoryBuilder, allowing an allow-list of variables. The example shows creating the repository, passing it to create(), and loading the environment.

```php
public static function create(RepositoryInterface $repository, $paths, $names = null, bool $shortCircuit = true, ?string $fileEncoding = null)
```

```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
    ->allowList(['FOO', 'BAR'])
    ->make();

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

--------------------------------

### Dotenv\Dotenv static factory usage examples

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv-Create.md

Shows three ways to instantiate Dotenv via static factory methods. The first uses createImmutable with a single path and default settings. The second passes a custom name array, disables short-circuiting, and sets UTF-8 encoding. The third uses createMutable with multiple paths and names, where each (path, name) pair becomes a candidate file.

```php
// Single path, default name, short-circuit on: load .env from the app dir
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
```

```php
// Custom name + encoding, merge all readable files
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, ['myconfig', 'myconfig.local'], false, 'UTF-8');
```

```php
// Multiple paths and names: each (path, name) pair is a candidate file
$dotenv = Dotenv\Dotenv::createMutable([__DIR__.'/app', '/etc/app'], ['.env', '.env.local']);
```

--------------------------------

### V4 example: Load variables without loading into environment

Source: https://github.com/vlucas/phpdotenv/blob/master/UPGRADING.md

Demonstrates how to read a file and process variable interpolations without actually loading the variables into the environment, using the Loader class directly with a repository built from ArrayAdapter.

```php
<?php

use Dotenv\Repository\Adapter\ArrayAdapter;
use Dotenv\Repository\RepositoryBuilder;
use Dotenv\Loader\Loader;

$adapters = [new ArrayAdapter()];

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

$variables = (new Loader())->load($repository, $content);
```

--------------------------------

### StoreBuilder::createWithDefaultName()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

Static factory method that returns a `StoreBuilder` configured to look for the default `.env` file. This is the most common starting point for building a store.

```APIDOC
## `StoreBuilder::createWithDefaultName()`

### Description
Creates a new `StoreBuilder` instance pre-configured to search for the default `.env` file. This is the equivalent of the internal store used by `Dotenv::createImmutable`.

### Method
`createWithDefaultName()`

### Signature
```php
public static function createWithDefaultName();
```

### Returns
- `StoreBuilder` - A new builder with the default name `.env`.
```

--------------------------------

### createImmutable usage

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv-Create.md

Example of creating an immutable Dotenv instance where existing environment variables are preserved.

```php
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load(); // existing $_ENV / $_SERVER values win
```

--------------------------------

### createArrayBacked usage

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv-Create.md

Example of creating an array-backed Dotenv instance for validation and testing without touching the real environment.

```php
$dotenv = Dotenv\Dotenv::createArrayBacked(__DIR__);
$vars = $dotenv->load();
$dotenv->required('FOO')->isInteger();
```

--------------------------------

### createWithNoAdapters()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/RepositoryBuilder.md

Static factory method that returns an empty RepositoryBuilder with no readers or writers. Use this as the starting point for building a repository with custom adapters.

```APIDOC
## createWithNoAdapters()

### Description
Returns an empty RepositoryBuilder with no readers and no writers. A repository built from this builder cannot read or write environment variables unless adapters are added.

### Method
`public static function createWithNoAdapters()`

### Returns
- **RepositoryBuilder** - An empty builder instance.

### Example
```php
$builder = RepositoryBuilder::createWithNoAdapters();
```
```

--------------------------------

### createUnsafeImmutable usage

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv-Create.md

Example of creating an unsafe immutable Dotenv instance that includes the putenv/getenv adapter.

```php
$dotenv = Dotenv\Dotenv::createUnsafeImmutable(__DIR__);
$dotenv->load(); // preserves existing values, incl. values only visible via getenv()
```

--------------------------------

### Loading a single entry with Dotenv\Loader\Loader

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Loader.md

Example of using the Loader to load a single entry into a repository. The entry 'A' with value '1' is loaded, and the result is an array with 'A' mapped to '1'.

```php
$loader = new Dotenv\Loader\Loader();
$entries = [new Dotenv\Parser\Entry('A', Dotenv\Parser\Value::create('1', []))];
$loader->load($repository, $entries); // ['A' => '1']
```

--------------------------------

### assert() usage example

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Validator.md

Example usage of the assert() method. It requires the TOKEN variable to be present and longer than 3 characters, otherwise a ValidationException is thrown with a message combining the variable name and the provided suffix.

```php
// Every listed variable must be present AND longer than 3 characters
$dotenv->required('TOKEN')->assert(
    function ($value) { return $value !== null && strlen($value) > 3; },
    'is too short'
);
```

--------------------------------

### isBoolean() usage examples

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Validator.md

Usage examples for isBoolean(). The first requires FOO to be a boolean. The second checks DEBUG only when it is set. Throws ValidationException if the value is not a valid boolean.

```php
$dotenv->required('FOO')->isBoolean();
$dotenv->ifPresent('DEBUG')->isBoolean(); // only checked when DEBUG is set
```

--------------------------------

### Dotenv::required() usage

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Example of requiring a single variable and an array of variables after loading the environment.

```php
$dotenv = Dotenv\Dotenv::createMutable(__DIR__)->load();
$dotenv->required('DATABASE_DSN');
$dotenv->required(['DB_HOST', 'DB_NAME', 'DB_PASS']);
```

--------------------------------

### Parse an entry with EntryParser::parse()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Parser.md

Parses a raw line 'FOO="Hello World"' into an Entry object. The result is a Result type; check success() to get the Entry and its Value, or error() to get the error message string.

```php
$result = Dotenv\Parser\EntryParser::parse('FOO="Hello World"');
if ($result->success()->isDefined()) {
    $entry = $result->success()->get();      // Entry(name: 'FOO')
    $value = $entry->getValue()->get();      // Value, getChars() === 'Hello World'
} else {
    $error = $result->error()->get();        // string cause
}
```

--------------------------------

### Lexer::lex() usage example

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Parser-Value.md

Shows how Lexer::lex() yields tokens for a string with an escaped newline.

```php
// Internally used by EntryParser::parseValue:
foreach (Dotenv\Parser\Lexer::lex('"a\\nb"') as $token) {
    // '"' -> 'a' -> '\\' -> 'n' -> 'b' -> '"'
}
```

--------------------------------

### Using required() with single and multiple variables

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Validator.md

Example usage of required() with a single variable and an array of variables.

```php
$dotenv->required('DATABASE_DSN');
$dotenv->required(['DB_HOST', 'DB_NAME']);
```

--------------------------------

### Add ArrayAdapter reader to default builder

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/RepositoryBuilder.md

Example usage of addReader() with a class-string adapter. Creates a builder with default adapters and appends ArrayAdapter::class as a reader. The builder is assigned to $builder.

```php
$builder = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
    ->addReader(Dotenv\Repository\Adapter\ArrayAdapter::class);
```

--------------------------------

### Using PutenvAdapter with unsafe variants or manual RepositoryBuilder

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Adapters.md

Shows two ways to use PutenvAdapter: via the unsafe factory methods (createUnsafeImmutable) or by manually adding the adapter to a RepositoryBuilder. The example also demonstrates that setting a name containing a NUL byte ("BAD\0NAME") returns false, while a normal name ('GOOD') returns true and is visible to getenv().

```php
// "Unsafe" variants wire PutenvAdapter in for you:
$dotenv = Dotenv\Dotenv::createUnsafeImmutable(__DIR__);
$dotenv->load();
$val = getenv('S3_BUCKET');

// Or add it manually:
$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\PutenvAdapter::class)
    ->make();
$ok = $repository->set("BAD\0NAME", 'x'); // false — NUL bytes in a name are rejected
$ok = $repository->set('GOOD', 'x');       // true — visible to getenv('GOOD')
```

--------------------------------

### Value::blank() - Create empty Value

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Parser-Value.md

Creates a new Value instance with empty characters and no variable references. Used to start building a value from scratch.

```php
public static function blank()
```

--------------------------------

### Iterating parsed entries with Entry::getName() and getValue()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Parser.md

Shows how to iterate over the result of `Parser::parse()` and access each entry's name and value. `getValue()` returns an `Option`, so `getOrElse(null)` is used to get the value or null.

```php
foreach ($parser->parse($content) as $entry) {
    $name = $entry->getName();               // string
    $value = $entry->getValue()->getOrElse(null); // Value|null
}
```

--------------------------------

### StoreBuilder make() method

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

Returns a new FileStore with the configured paths, names, shortCircuit, and fileEncoding. Throws nothing.

```php
public function make()
```

--------------------------------

### Dotenv::parse() example with nested variables

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Example of parsing a dotenv string with nested variable resolution. Nested variables are resolved only against earlier variables in the same string.

```php
// Returns ['FOO' => 'Bar', 'BAZ' => 'Hello Bar']
Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello \${FOO}\"");
```

--------------------------------

### Use ApacheAdapter with default adapters and load .env

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Adapters.md

Builds a repository with the default adapters plus ApacheAdapter, then creates a Dotenv instance and loads the .env file. ApacheAdapter uses apache_getenv()/apache_setenv() and is only available when PHP runs as an Apache module.

```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\ApacheAdapter::class)
    ->make();
$dotenv = Dotenv\Dotenv::create($repository, __DIR__);
$dotenv->load();
```

--------------------------------

### make() usage with custom adapters and immutability

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/RepositoryBuilder.md

Builds a repository with no default adapters, adds EnvConstAdapter for reading and PutenvAdapter for writing, enables immutability, and then creates a Dotenv instance with it.

```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\EnvConstAdapter::class)
    ->addWriter(Dotenv\Repository\Adapter\PutenvAdapter::class)
    ->immutable()
    ->make(); // reads only $_ENV, writes $_ENV + putenv, never overwrites existing values

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

--------------------------------

### assertNullable() usage example

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Validator.md

Example usage of the assertNullable() method. It only rejects the FOO variable when it is set to a non-empty value that is not longer than 3 characters; if FOO is unset, the validation passes.

```php
// Only reject FOO when it is actually set to a non-empty value
$dotenv->ifPresent('FOO')->assertNullable(function ($value) {
    return strlen($value) > 3;
}, 'is too short');
```

--------------------------------

### Create RepositoryBuilder with default adapters

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/RepositoryBuilder.md

Returns a RepositoryBuilder whose readers and writers are the default adapters: ServerConstAdapter::class, then EnvConstAdapter::class (constant DEFAULT_ADAPTERS, line 25-31). Each adapter is instantiated via its create() and only kept if isDefined() (see defaultAdapters(), lines 103-117), so adapters are individually skipped when their backend is unavailable. Ordered: $_SERVER before $_ENV.

```php
public static function createWithDefaultAdapters()
```

--------------------------------

### ValidationException message for empty variable

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Example exception message when a required variable is empty.

```text
One or more environment variables failed assertions: DATABASE_DSN is empty.
```

--------------------------------

### ValidationException message for missing variable

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Example exception message when a required variable is missing.

```text
One or more environment variables failed assertions: DATABASE_DSN is missing.
```

--------------------------------

### RepositoryBuilder adapter configuration before and after V5

Source: https://github.com/vlucas/phpdotenv/blob/master/UPGRADING.md

Shows the old and new ways to build a repository with adapters. The old method uses withReaders and withWriters, while the new method uses createWithNoAdapters and addAdapter/addWriter. The new method requires explicitly specifying adapters and can accept class names or instances.

```php
$repository = Dotenv\Repository\RepositoryBuilder::create()
    ->withReaders([
        new Dotenv\Repository\Adapter\EnvConstAdapter(),
    ])
    ->withWriters([
        new Dotenv\Repository\Adapter\EnvConstAdapter(),
        new Dotenv\Repository\Adapter\PutenvAdapter(),
    ])
    ->make();
```

```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\EnvConstAdapter::class)
    ->addWriter(Dotenv\Repository\Adapter\PutenvAdapter::class)
    ->make();
```

--------------------------------

### ValidationException message for non-integer variable

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Example exception message when a variable fails the integer check.

```text
One or more environment variables failed assertions: FOO is not an integer.
```

--------------------------------

### createWithNoAdapters() factory method

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/RepositoryBuilder.md

Returns an empty RepositoryBuilder with no readers or writers. A repository built from it cannot read or write unless adapters are added.

```php
public static function createWithNoAdapters()
```

--------------------------------

### FileStore::__construct

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

Creates a new FileStore instance with the given file paths, short-circuit flag, and optional file encoding.

```APIDOC
## FileStore::__construct

### Description
Creates a new FileStore instance with the given file paths, short-circuit flag, and optional file encoding.

### Method
__construct

### Signature
```php
public function __construct(array $filePaths, bool $shortCircuit, ?string $fileEncoding = null)
```

### Parameters
- `$filePaths` (string[]) - Required - Full candidate file paths
- `$shortCircuit` (bool) - Required - Stop after the first readable file
- `$fileEncoding` (string|null) - Optional - Encoding to convert from. Default: `null`

```

--------------------------------

### Dotenv::required() with notEmpty() exception handling

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Example of catching a ValidationException when a required variable is empty.

```php
try {
    $dotenv->required('DATABASE_DSN')->notEmpty();
} catch (Dotenv\Exception\ValidationException $e) {
    // "One or more environment variables failed assertions: DATABASE_DSN is empty."
}
```

--------------------------------

### Custom repository with EnvConst and Putenv adapters

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Builds a custom repository that writes to $_ENV and putenv but reads only from $_ENV, and never replaces variables already set before loading. Use this to customize which adapters are used and to enforce immutability.

```php
$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();
```

--------------------------------

### Dotenv\Dotenv::create

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv-Create.md

Creates a Dotenv instance with a custom repository. Accepts a repository, paths, names, short-circuit flag, and file encoding.

```APIDOC
## Dotenv\Dotenv::create

### Description
Creates a new Dotenv instance with a custom repository. The repository is provided as the first argument, followed by paths, names, short-circuit flag, and file encoding.

### Method
static factory method

### Signature
`public static function create($repository, $paths, $names = null, $shortCircuit = true, $fileEncoding = null): Dotenv\Dotenv`

### Parameters
- **$repository** (RepositoryInterface) - Required - The repository to use for storing environment variables.
- **$paths** (string|string[]) - Required - Directory path(s) to search for the env file(s).
- **$names** (string|string[]|null) - Optional - File name(s) to look for inside each path. Defaults to `.env` if null.
- **$shortCircuit** (bool) - Optional - When true, only the first readable file is loaded; when false, all readable files are merged. Defaults to true.
- **$fileEncoding** (string|null) - Optional - Character encoding of the file(s), converted to UTF-8. Defaults to null (uses mbstring conversion default).

### Return Value
Returns a `Dotenv\Dotenv` instance.

### Exceptions
Does not throw on its own. Exceptions may arise from `load()`/`safeLoad()`.
```

--------------------------------

### Safely load .env with safeLoad

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Load .env without throwing an exception when the file is absent.

```php
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->safeLoad();
```

--------------------------------

### Dotenv::parse() exception handling

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Example of catching an InvalidFileException when parsing malformed content with an unterminated quote.

```php
try {
    Dotenv\Dotenv::parse("NAME=unterminated\"");
} catch (Dotenv\Exception\InvalidFileException $e) {
    // "Failed to parse dotenv file. Encountered a missing closing quote at [...]."
}
```

--------------------------------

### create()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv-Create.md

Creates a new Dotenv instance with a custom repository. The repository must implement RepositoryInterface and can be built using RepositoryBuilder.

```APIDOC
## create()

### Description
Creates a new Dotenv instance using a custom repository. The repository must implement RepositoryInterface and can be built using RepositoryBuilder.

### Method
create

### Signature
public static function create(RepositoryInterface $repository, $paths, $names = null, bool $shortCircuit = true, ?string $fileEncoding = null)

### Parameters
- **$repository** (Dotenv\Repository\RepositoryInterface) - Required - Any repository; build one with RepositoryBuilder. NOTE: by default RepositoryBuilder::createWithDefaultAdapters() is mutable (allows overwriting existing variables)
- **$paths** (mixed) - Required - Paths to the .env file(s)
- **$names** (mixed) - Optional - Names of the .env files
- **$shortCircuit** (bool) - Optional - Whether to short circuit on first found file (default: true)
- **$fileEncoding** (?string) - Optional - Encoding of the .env file

### Returns
- **Dotenv\Dotenv** - A new Dotenv instance using the supplied repository.

### Example
```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
    ->allowList(['FOO', 'BAR'])
    ->make();

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

--------------------------------

### Constructor signature for Dotenv\Dotenv

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Shows the constructor signature with four required parameters: StoreInterface, ParserInterface, LoaderInterface, and RepositoryInterface. The constructor itself does not throw; exceptions surface from load().

```php
public function __construct(
    StoreInterface $store,
    ParserInterface $parser,
    LoaderInterface $loader,
    RepositoryInterface $repository
)
```

--------------------------------

### Using ifPresent() to validate optional variables

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Example usage of ifPresent() to validate that 'FOO' is an integer and 'DEBUG' is a boolean, only if they are present in the environment.

```php
$dotenv->ifPresent('FOO')->isInteger();
$dotenv->ifPresent('DEBUG')->isBoolean();
```

--------------------------------

### allowList() usage

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/RepositoryBuilder.md

Creates a repository builder with default adapters and sets an allow list of variable names that may be written or deleted.

```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
    ->allowList(['FOO', 'BAR'])
    ->make();
```

--------------------------------

### Allow list variables with RepositoryBuilder

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Creates a repository with default adapters and an allow list so only the listed variables (FOO and BAR) are loaded.

```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
    ->allowList(['FOO', 'BAR'])
    ->make();

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

--------------------------------

### Catching ValidationException from required()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Validator.md

Example of catching the ValidationException thrown when a required variable is missing. The exception message includes the variable name and 'is missing'.

```php
try {
    $dotenv->required('DATABASE_DSN');
} catch (Dotenv\Exception\ValidationException $e) {
    // "One or more environment variables failed assertions: DATABASE_DSN is missing."
}
```

--------------------------------

### RepositoryInterface definition

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Repository.md

Defines the contract for a dotenv repository. All methods accept a non-empty string name; get, set, and clear may throw InvalidArgumentException.

```php
interface RepositoryInterface
{
    public function has(string $name);
    public function get(string $name);
    public function set(string $name, string $value);
    public function clear(string $name);
}
```

--------------------------------

### FileStore constructor

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

Constructor for FileStore. Accepts an array of candidate file paths, a boolean to stop at the first readable file, and an optional file encoding.

```php
public function __construct(array $filePaths, bool $shortCircuit, ?string $fileEncoding = null)
```

--------------------------------

### Dotenv\Dotenv::__construct

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Documentation for the Dotenv\Dotenv constructor, which creates a new instance by injecting collaborators.

```APIDOC
## Constructor

### Description
Creates a new `Dotenv\Dotenv` instance by wiring together a store, parser, loader, and repository. This constructor is the primary way to instantiate the facade when custom collaborators are needed.

### Method
`__construct`

### Signature
```php
public function __construct(
    StoreInterface $store,
    ParserInterface $parser,
    LoaderInterface $loader,
    RepositoryInterface $repository
)
```

### Parameters
- **$store** (`Dotenv\Store\StoreInterface`) - Required - Supplies raw file/string content on `read()`; throws `InvalidEncodingException`/`InvalidPathException`.
- **$parser** (`Dotenv\Parser\ParserInterface`) - Required - Turns content into `Entry[]`; throws `InvalidFileException`.
- **$loader** (`Dotenv\Loader\LoaderInterface`) - Required - Loads entries into the repository (nested-variable resolution happens here).
- **$repository** (`Dotenv\Repository\RepositoryInterface`) - Required - Target store for `get`/`set`/`clear`/`has` of environment variables.

### Returns
A new `Dotenv` instance.

### Throws
Nothing at construction; exceptions surface from `load()`.

### Example
```php
$dotenv = new Dotenv\Dotenv(
    new Dotenv\Store\StringStore("FOO=Bar"),
    new Dotenv\Parser\Parser(),
    new Dotenv\Loader\Loader(),
    Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
        ->addAdapter(Dotenv\Repository\Adapter\ArrayAdapter::class)
        ->make()
);
$vars = $dotenv->load(); // ['FOO' => 'Bar']
```
```

--------------------------------

### Create immutable repository and set variable

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Repository.md

Creates an immutable repository using the default adapters and attempts to set a variable. The set operation returns false if the variable was already defined externally or loaded by an earlier immutable load, preventing overwrites.

```php
// With an immutable repository nothing from the file can clobber a variable
// that already exists in $_SERVER or was loaded by an earlier immutable load.
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()->immutable()->make();
$repository->set('FOO', 'x'); // false if FOO was already present before this session's loads
```

--------------------------------

### StringStore constructor

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

Constructor for StringStore. Takes a string content.

```php
public function __construct(string $content)
```

--------------------------------

### load() error handling with try-catch

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Shows how to catch the three exceptions load() can throw: InvalidPathException, InvalidFileException, and InvalidEncodingException. Use createMutable for a mutable repository.

```php
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);
try {
    $dotenv->load();
} catch (Dotenv\Exception\InvalidPathException $e) {
    // .env file could not be found/read
} catch (Dotenv\Exception\InvalidFileException $e) {
    // parse error, e.g. a bad escape sequence
} catch (Dotenv\Exception\InvalidEncodingException $e) {
    // file bytes could not be converted to UTF-8
}
```

--------------------------------

### Value::create() - Create Value with chars and vars

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Parser-Value.md

Creates a new Value instance with the given literal characters and variable offsets. The $vars array should contain byte/char offsets of variable starts.

```php
public static function create(string $chars, array $vars)
```

--------------------------------

### load()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Loads environment variables from the .env file into the repository. Returns an array of variables actually written, with null values indicating cleared variables. Throws exceptions for invalid path, encoding, or file content.

```APIDOC
## `load()`

### Description
Loads environment variables from the .env file into the repository. Returns an array of variables actually written, with null values indicating cleared variables. Throws exceptions for invalid path, encoding, or file content.

### Method
`load()`

### Signature
```php
public function load()
```

### Parameters
None.

### Returns
- **array<string, string|null>** - The variables actually written to the repository. A value of `null` means the variable was cleared (an entry with no `=`), a `string` means it was set. Variables skipped (e.g. by immutability, an allow list, or an adapter reporting failure) are omitted, as are variables whose set attempt failed.

### Throws
- `Dotenv\Exception\InvalidPathException` - If the .env file could not be found or read.
- `Dotenv\Exception\InvalidEncodingException` - If the file bytes could not be converted to UTF-8.
- `Dotenv\Exception\InvalidFileException` - If there is a parse error, e.g. a bad escape sequence.

### Behavior
`parse($this->store->read())` then `load($this->repository, $entries)`.

### Example
```php
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$vars = $dotenv->load();
foreach ($vars as $name => $value) {
    // $value is string|null
}
```

### Error Handling Example
```php
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);
try {
    $dotenv->load();
} catch (Dotenv\Exception\InvalidPathException $e) {
    // .env file could not be found/read
} catch (Dotenv\Exception\InvalidFileException $e) {
    // parse error, e.g. a bad escape sequence
} catch (Dotenv\Exception\InvalidEncodingException $e) {
    // file bytes could not be converted to UTF-8
}
```
```

--------------------------------

### make()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/RepositoryBuilder.md

Builds and returns the final repository instance. It composites readers and writers, optionally wrapping the writer with ImmutableWriter and GuardedWriter based on the builder's configuration.

```APIDOC
## `make()`

### Description
Builds and returns the final repository instance. It composites readers and writers, optionally wrapping the writer with `ImmutableWriter` and `GuardedWriter` based on the builder's configuration.

### Method
`make()`

### Returns
`\Dotenv\Repository\RepositoryInterface` - The composed repository instance.

### Throws
Nothing.

### Example
```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\EnvConstAdapter::class)
    ->addWriter(Dotenv\Repository\Adapter\PutenvAdapter::class)
    ->immutable()
    ->make(); // reads only $_ENV, writes $_ENV + putenv, never overwrites existing values

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

--------------------------------

### Resolving nested variables with Dotenv\Loader\Resolver

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Loader.md

Example of resolving a nested variable reference. It creates a repository with an array adapter, sets BASE_DIR, and resolves a value containing ${BASE_DIR}/cache. The result is '/var/webroot/cache'. Missing variables are left verbatim.

```php
$repo = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\ArrayAdapter::class)
    ->make();
$repo->set('BASE_DIR', '/var/webroot');
$resolved = Dotenv\Loader\Resolver::resolve(
    $repo,
    Dotenv\Parser\Value::create('${BASE_DIR}/cache', [0])
);
// '/var/webroot/cache' — and '${MISSING}/x' would stay '${MISSING}/x'
```

--------------------------------

### Parsing dotenv content with Parser

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Parser.md

Shows how to instantiate the Parser and parse a string containing two lines. The resulting entries provide getName() and getValue() methods, where getValue() returns an Option that can be unwrapped with getOrElse(null).

```php
$parser = new Dotenv\Parser\Parser();
$entries = $parser->parse("FOO=Bar\nBAZ=Qux");
foreach ($entries as $entry) {
    $name = $entry->getName();        // 'FOO'
    $value = $entry->getValue();      // Option<Value> — use getOrElse(null)
}
```

--------------------------------

### Dotenv\Parser\Value class definition

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/types.md

Represents a parsed value with literal characters and offsets where variable references start. The constructor is private; use blank() or create(). Produced by EntryParser, consumed by Loader\Loader::load, Loader\Resolver::resolve, and Entry::getValue().

```php
final class Value
{
    private function __construct(string $chars, array $vars);
    public static function blank();                          // -> Value
    public static function create(string $chars, array $vars); // -> Value
    public function append(string $chars, bool $var);        // -> Value
    public function getChars();                              // -> string
    public function getVars();                               // -> int[] (descending)
}
```

--------------------------------

### AdapterInterface extends Reader and Writer

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Adapters.md

Combines ReaderInterface and WriterInterface for a backend usable as both reader and writer. The static create method returns an Option<AdapterInterface> indicating backend availability.

```php
interface AdapterInterface extends ReaderInterface, WriterInterface
{
    public static function create();
}
```

--------------------------------

### createMutable() with default adapters

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv-Create.md

Creates a mutable Dotenv instance using default adapters. Loaded values overwrite existing environment variables in $_SERVER and $_ENV.

```php
public static function createMutable($paths, $names = null, bool $shortCircuit = true, ?string $fileEncoding = null)
```

```php
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);
$dotenv->load(); // overwrites $_SERVER / $_ENV entries
```

--------------------------------

### allowedValues() method signature and usage

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Validator.md

The allowedValues method signature and usage examples. The method throws ValidationException with a message suffix 'is not one of [<comma-joined choices>]' when the value is not in the strict in_array check. Null values pass. The method returns $this for chaining.

```php
public function allowedValues(array $choices)
```

```php
$dotenv->required('SESSION_STORE')->allowedValues(['Filesystem', 'Memcached']);
```

```php
try {
    $dotenv->ifPresent('SESSION_STORE')->allowedValues(['Filesystem']);
} catch (Dotenv\Exception\ValidationException $e) {
    // "... SESSION_STORE is not one of [Filesystem]."
}
```

--------------------------------

### Catch ValidationException from required()->notEmpty()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/errors.md

Catches a ValidationException thrown by Validator::assert() when required environment variables fail assertions. The example requires DB_HOST and DB_NAME to be not empty; the exception message lists each failing variable with its suffix, e.g., "DB_HOST is empty, DB_NAME is missing."

```php
try {
    $dotenv->required(['DB_HOST', 'DB_NAME'])->notEmpty();
} catch (Dotenv\Exception\ValidationException $e) {
    // "One or more environment variables failed assertions: DB_HOST is empty, DB_NAME is missing."
}
```

--------------------------------

### Load .env with createImmutable

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Load environment variables from a .env file in the given directory. Throws an exception if the file is missing.

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

--------------------------------

### allowedRegexValues() method signature and usage

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Validator.md

The allowedRegexValues method signature and usage examples. The regex is applied as an unanchored match; anchor it yourself to match the whole value. Throws ValidationException with either 'does not match "<regex>"' or 'could not be validated against the invalid regular expression "<regex>"' when the pattern is invalid. Null values pass. Returns $this.

```php
public function allowedRegexValues(string $regex)
```

```php
$dotenv->required('FOO')->allowedRegexValues('([[:lower:]]{3})');
```

```php
try {
    $dotenv->ifPresent('FOO')->allowedRegexValues('('); // invalid regex
} catch (Dotenv\Exception\ValidationException $e) {
    // "... could not be validated against the invalid regular expression \"(\"."
}
```

--------------------------------

### StoreBuilder::make()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

Builds the final store instance. This method is the culmination of the builder pattern and returns a `FileStore` configured with the accumulated paths, names, and options.

```APIDOC
## `StoreBuilder::make()`

### Description
Builds and returns a `StoreInterface` instance based on the current builder configuration. The returned store is a `FileStore` that uses the configured paths, names, short-circuit flag, and file encoding.

### Method
`make()`

### Signature
```php
public function make();
```

### Returns
- `\Dotenv\Store\StoreInterface` - A new `FileStore` instance.

### Example
```php
// Equivalent to Dotenv::createImmutable's internal store: .env in one path
$store = Dotenv\Store\StoreBuilder::createWithDefaultName()
    ->addPath(__DIR__)
    ->shortCircuit()
    ->make();

// Custom names/encodings and merging across several files:
$store = Dotenv\Store\StoreBuilder::createWithNoNames()
    ->addPath('/srv/app')
    ->addPath('/srv/app/config')
    ->addName('.env')
    ->addName('.env.local')
    ->fileEncoding('UTF-8')
    ->make();
$content = $store->read();
```
```

--------------------------------

### Load environment variables from file with createArrayBacked()->load()

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Loads environment variables from a .env file in the given directory and returns an array. This is the equivalent of parse() but reads from a file instead of a string.

```php
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
```

--------------------------------

### FileStore read() method

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

Reads and joins the contents of the environment files. Throws InvalidPathException if no file paths are provided or if none are readable.

```php
public function read()
```

--------------------------------

### StringStore::__construct

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

Creates a new StringStore instance with the given content string.

```APIDOC
## StringStore::__construct

### Description
Creates a new StringStore instance with the given content string.

### Method
__construct

### Signature
```php
public function __construct(string $content)
```

### Parameters
- `$content` (string) - Required - The content string to store.

```

--------------------------------

### Using RepositoryBuilder::allowList() with GuardedWriter

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Repository.md

Creates a repository with an allow list containing only 'FOO'. Setting 'FOO' returns true, while setting 'BAR' returns false because it is not in the allow list.

```php
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
    ->allowList(['FOO'])
    ->make();
$repository->set('FOO', '1'); // true
$repository->set('BAR', '1'); // false — BAR not in the allow list
```

--------------------------------

### Load custom filename with createImmutable

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Load a custom-named configuration file instead of .env by passing the filename as the second parameter.

```php
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');
$dotenv->load();
```

--------------------------------

### StoreInterface::read()

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Store.md

The `read()` method is the core contract of the `StoreInterface`. It returns the raw dotenv content as a string and may throw exceptions for invalid encoding or path issues.

```APIDOC
## `StoreInterface::read()`

### Description
Reads the dotenv content from the store. This is the primary method that the `Dotenv\Loader` pipeline calls via `Dotenv::load()`.

### Method
`read()`

### Signature
```php
public function read();
```

### Returns
- `string` - The file/dotenv content.

### Throws
- `\Dotenv\Exception\InvalidEncodingException` - If the file encoding is invalid.
- `\Dotenv\Exception\InvalidPathException` - If the file path is invalid.
```

--------------------------------

### safeLoad() usage with createImmutable

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv.md

Creates an immutable Dotenv instance and calls safeLoad(). Returns an empty array if there is no readable .env file.

```php
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$vars = $dotenv->safeLoad(); // [] if there is no readable .env file
```

--------------------------------

### Dotenv\Dotenv::createMutable

Source: https://github.com/vlucas/phpdotenv/blob/master/_autodocs/api-reference/Dotenv-Create.md

Creates a Dotenv instance with a mutable repository. Accepts paths, names, short-circuit flag, and file encoding.

```APIDOC
## Dotenv\Dotenv::createMutable

### Description
Creates a new Dotenv instance with a mutable repository. The repository is built from the provided paths and names, using the given short-circuit and file encoding settings.

### Method
static factory method

### Signature
`public static function createMutable($paths, $names = null, $shortCircuit = true, $fileEncoding = null): Dotenv\Dotenv`

### Parameters
- **$paths** (string|string[]) - Required - Directory path(s) to search for the env file(s).
- **$names** (string|string[]|null) - Optional - File name(s) to look for inside each path. Defaults to `.env` if null.
- **$shortCircuit** (bool) - Optional - When true, only the first readable file is loaded; when false, all readable files are merged. Defaults to true.
- **$fileEncoding** (string|null) - Optional - Character encoding of the file(s), converted to UTF-8. Defaults to null (uses mbstring conversion default).

### Return Value
Returns a `Dotenv\Dotenv` instance.

### Exceptions
Does not throw on its own. Exceptions may arise from `load()`/`safeLoad()`.
```

--------------------------------

### Comment syntax in .env files

Source: https://github.com/vlucas/phpdotenv/blob/master/README.md

Shows how to add comments to a .env file using the # character. A # begins a comment anywhere outside of quotes, even when it directly follows an unquoted value.

```shell
# this is a comment
VAR="value" # comment
VAR=value # comment
```
Tokens:
Raw