ddrv/env

Read variables from environment or .env file

v3.0.0 2025-04-15 19:07 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5 || ^11.5 || ^12.1
• squizlabs/php_codesniffer: ^3.7

MIT

• Ivan Dudarev

• environment
• env
• .env

README

Read variables from environment or .env file

Install

composer require ddrv/env:^3.0

Usage

For example, we have a global array

$_ENV = [
    'APP_VAR_1' => 'value1',
    'APP_VAR_2' => 'value2',
];

and dotenv file /path/to/project/.env

# /path/to/project/.env

APP_VAR_3=value3

System environment

<?php

use Ddrv\Env\Env;
use Ddrv\Env\VariableProvider\EnvVariableProvider;

$env = new Env(new EnvVariableProvider());

$env->get('APP_VAR_1'); // returns 'value1'
$env->get('APP_VAR_2'); // returns 'value2'
$env->get('APP_VAR_3'); // returns null because $_ENV has not 'APP_VAR_3' key
$env->get('APP_VAR_3', 'default3'); // returns 'default3' because $_ENV has not 'APP_VAR_3' key but passed parameter $default

dotenv file

<?php

use Ddrv\Env\Env;
use Ddrv\Env\VariableProvider\FileVariableProvider;

$env = new Env(new FileVariableProvider('/path/to/project/.env'));

$env->get('APP_VAR_1'); // returns null because APP_VAR_3 not defined in /path/to/project/.env file
$env->get('APP_VAR_3'); // returns 'value3'

Memory

<?php

use Ddrv\Env\Env;
use Ddrv\Env\VariableProvider\MemoryVariableProvider;

$variableProvider = new MemoryVariableProvider([
    'APP_VAR_4' => 'value4',
])
$env = new Env($variableProvider);

$env->get('APP_VAR_4'); // returns 'value4'
$env->get('APP_VAR_5'); // returns null
$variableProvider->set('APP_VAR_5', 'value5');
$env->get('APP_VAR_5'); // returns 'value5'

Prefixes

<?php

use Ddrv\Env\Env;
use Ddrv\Env\VariableProvider\EnvVariableProvider;
use Ddrv\Env\VariableProvider\PrefixedVariableProvider;

$env = new Env(new PrefixedVariableProvider(new EnvVariableProvider(), 'APP_'));

$env->get('VAR_1'); // returns 'value1'
$env->get('VAR_3'); // returns null

Resolving variables

<?php

use Ddrv\Env\Env;
use Ddrv\Env\VariableProvider\EnvVariableProvider;
use Ddrv\Env\VariableProvider\MemoryVariableProvider;

$env = new Env(new ResolveVariableProvider(new MemoryVariableProvider([
    'SCHEME_1' => 'http',
    'PATH_1' => '/path/to/file',
    'HOST_1' => '127.0.0.1',
    'PORT_1' => '8080',
    'TOKEN_1' => 'secret',
    'CYCLED_1' => '${CYCLED_2}',
    'CYCLED_2' => '${CYCLED_3}',
    'CYCLED_3' => '${CYCLED_1}',
    'URL_1' => '${SCHEME_1}://${HOST_1}:${PORT_1}${PATH_1}',
    'URL_2' => '${SCHEME_2:-https}://${HOST_2:-localhost}:${PORT_2:-1080}${PATH_1:-/}',
    'URL_3' => 'http://localhost:1080/api/version?token=\${TOKEN_1}',
    'URL_4' => 'http://localhost:1080/api/version?token=\\\\${TOKEN_1}',
    'URL_5' => 'http://localhost:1080/api/version?token=${TOKEN_2:?Token is required.}',
    'URL_6' => 'http://localhost:1080/${CYCLED_1}',
])));

$env->get('URL_1'); // returns 'http://127.0.0.1:8080/path/to/file'
$env->get('URL_2'); // returns 'https://localhost:1080/'
$env->get('URL_3'); // returns 'http://localhost:1080/api/version?token=${TOKEN_1}'
$env->get('URL_4'); // returns 'http://localhost:1080/api/version?token=\secret'
$env->get('URL_5'); // throws Ddrv\Env\Exception\VariableUndefined with message 'Variable TOKEN_2 undefined. Token is required.'
$env->get('URL_6'); // throws \Ddrv\Env\Exception\CyclicalDependencyDetected with message 'Cyclical dependency detected (URL_6 -> CYCLED_1 -> CYCLED_2 -> CYCLED_3 -> CYCLED_1).'

Composite

<?php

use Ddrv\Env\Env;
use Ddrv\Env\VariableProvider\CompositeVariableProvider;
use Ddrv\Env\VariableProvider\EnvVariableProvider;
use Ddrv\Env\VariableProvider\FileVariableProvider;
use Ddrv\Env\VariableProvider\MemoryVariableProvider;

$env = new Env(new CompositeVariableProvider(
    new EnvVariableProvider(),
    new FileVariableProvider('/path/to/project/.env'),
    new MemoryVariableProvider([
        'APP_VAR_1' => 'other1',
        'APP_VAR_2' => 'other2',
        'APP_VAR_3' => 'other3',
        'APP_VAR_4' => 'other4',
    ]),
));

$env->get('APP_VAR_1'); // returns 'value1' because $_ENV has 'APP_VAR_1' key and priority of EnvVariableProvider is higher than that of MemoryVariableProvider
$env->get('APP_VAR_2'); // returns 'value2' because $_ENV has 'APP_VAR_2' key and priority of EnvVariableProvider is higher than that of MemoryVariableProvider
$env->get('APP_VAR_3'); // returns 'value3' because APP_VAR_3 defined in /path/to/project/.env file and priority of FileVariableProvider is higher than that of MemoryVariableProvider
$env->get('APP_VAR_4'); // returns 'other4' because MemoryVariableProvider has 'APP_VAR_4' variable and $_ENV has not 'APP_VAR_4' key and APP_VAR_4 not defined in /path/to/project/.env file
$env->get('APP_VAR_5'); // returns null because none of the providers contain the variable APP_VAR_5
$env->get('APP_VAR_5', 'default5'); // returns 'default5'

Caching

<?php

use Ddrv\Env\Env;
use Ddrv\Env\VariableProvider\CachedVariableProvider;
use Ddrv\Env\VariableProvider\EnvVariableProvider;

$env = new Env(new CachedVariableProvider(
    new EnvVariableProvider(),
));

$env->get('APP_VAR_1'); // returns 'value1' because $_ENV has 'APP_VAR_1' key and priority of EnvVariableProvider is higher than that of MemoryVariableProvider

putenv('APP_VAR_1=');
$env->get('APP_VAR_1'); // returns 'value1' because CachedVariableProvider cache this value.
$env->reload();
$env->get('APP_VAR_1'); // returns '' because reload() method clear cache.