README

A powerful PHP library for resolving environment variables, constants, files, and other data sources using a flexible chain of modifiers. Inspired by Symfony's env processors but works standalone without framework dependencies.

It helps you to keep configs clean without commiting of sensitive data. Just store instructions which environment variable use while running. They look like %env(MY_VAR)%.

Features

• Chain modifiers - Combine multiple transformations: json:base64:env:MY_VAR
• Nested placeholders - Support for %env(file:%env(PATH_VAR)%)%
• Escaping - Use %% to output literal % characters
• Multiple data sources - Environment variables, constants, files, PHP includes
• Type casting - Convert to int, float, bool, string, JSON, CSV
• Encoding/Decoding - Base64, URL encoding, query string parsing
• Extensible - Custom post-processors for resolved values

Installation

composer require aeliot/env-resolver

Requirements

• PHP 8.2 or higher

Quick Start

String Processing with Placeholders

use Aeliot\EnvResolver\Service\StringProcessor;

$processor = new StringProcessor();

$_ENV['HOST'] = 'localhost';
$_ENV['PORT'] = '5432';

$config = 'postgres://%env(HOST)%:%env(PORT)%/database';
$result = $processor->process($config);
// Result: 'postgres://localhost:5432/database'

It allows to process entire config:

use Aeliot\EnvResolver\Service\StringProcessor;

$preparedConfig = (new StringProcessor())->process(file_get_contents('/path/to/config.yaml'));
// Result: all instructions '%env(MY_ENV_VAR)%' resolved to <my_env_var_value> 

Modifiers

Modifiers are chained using : separator and processed from right to left.

Data Sources

Type Casting

Encoding/Decoding

String Operations

Complex Types

Examples

Basic Usage

use Aeliot\EnvResolver\Service\Resolver;

$resolver = new Resolver();

// Simple environment variable
$_ENV['DATABASE_URL'] = 'mysql://localhost/mydb';
$value = $resolver->resolve('DATABASE_URL');
// Result: 'mysql://localhost/mydb'

// Explicit env modifier
$value = $resolver->resolve('env:DATABASE_URL');
// Result: 'mysql://localhost/mydb'

Chained Modifiers

// Base64 encoded JSON in environment variable
$_ENV['CONFIG'] = 'eyJkYiI6Im15c3FsIiwicG9ydCI6MzMwNn0='; // {"db":"mysql","port":3306}

$resolver = new Resolver();

// Decode base64, then parse JSON, then get 'port' key, then cast to int
$port = $resolver->resolve('int:key:port:json:base64:CONFIG');
// Result: 3306 (integer)

Nested Placeholders

$_ENV['CONFIG_FILE_PATH'] = '/etc/myapp/database.conf';

$processor = new StringProcessor();

// Inner placeholder resolves first, then outer uses the result
$config = '%env(file:%env(CONFIG_FILE_PATH)%)%';
$result = $processor->process($config);
// Result: contents of /etc/myapp/database.conf

Escaping Percent Signs

$processor = new StringProcessor();

$_ENV['DISCOUNT'] = '25';

$result = $processor->process('Get %env(DISCOUNT)%%% off!');
// Result: 'Get 25% off!'

// Double %% becomes single %
$result = $processor->process('100%% complete');
// Result: '100% complete'

// Escape entire placeholder
$result = $processor->process('Use %%env(VAR)%% syntax');
// Result: 'Use %env(VAR)% syntax'

Custom Post-Processor

$processor = new StringProcessor();

$_ENV['POSITION_CONFIG'] = 'eyJwYXRoIjoiL3BhdGgvdG8vZmlsZSIsImxpbmUiOiAxMjd9';

// Default: non-scalar values are JSON encoded
$result = $processor->process('%env(json:base64:POSITION_CONFIG)%');
// Result: '{"path":"/path/to/file","line": 127}'

// Custom: join array elements
$result = $processor->process(
    '%env(json:base64:direct:POSITION_CONFIG)%',
    static function (mixed $value, string $heap): string {
        if ('json:base64:direct:POSITION_CONFIG' === $heap){
            $value = implode(', ', $value);
        }
        return \is_string($value) ? $value : json_encode($value, \JSON_THROW_ON_ERROR);
    }
);
// Result: '/path/to/file:127'

Similarly, you may return tilda (~) for null-values when process YAML.

Reading from Files

$resolver = new Resolver();

// Read file contents
$content = $resolver->resolve('file:/etc/ssl/certs/ca.pem');

// Read file path from env, then read file
$_ENV['CERT_PATH'] = '/etc/ssl/certs/ca.pem';
$content = $resolver->resolve('file:env:CERT_PATH');

// Require PHP file that returns a value
$config = $resolver->resolve('require:/path/to/config.php');

URL Parsing

$_ENV['DATABASE_URL'] = 'mysql://user:pass@localhost:3306/mydb?charset=utf8';

$resolver = new Resolver();

$params = $resolver->resolve('url:DATABASE_URL');
// Result: [
//     'scheme' => 'mysql',
//     'host' => 'localhost',
//     'port' => 3306,
//     'user' => 'user',
//     'pass' => 'pass',
//     'path' => 'mydb',
//     'query' => 'charset=utf8',
//     'fragment' => null,
// ]

// Get specific part
$host = $resolver->resolve('key:host:url:DATABASE_URL');
// Result: 'localhost'

Working with Enums

enum Status: string {
    case ACTIVE = 'active';
    case INACTIVE = 'inactive';
}

$_ENV['USER_STATUS'] = 'active';

$resolver = new Resolver();
$status = $resolver->resolve('enum:Status:USER_STATUS');
// Result: Status::ACTIVE

Error Handling

The library throws typed exceptions for different error conditions:

All exceptions implement EnvResolverExceptionInterface.

Contributing

Check code quality before the creating of PR.

# All checks
composer check-all

# Individual checks
composer cs-fixer-check  # Code style
composer phpstan         # Static analysis
composer require-check   # Dependency check
composer unused          # Unused dependencies

# Run with Docker
docker compose run --rm php-cli php tools/phpunit.phar -c .scripts/phpunit/phpunit.xml

License

This project is licensed under the MIT License - see the LICENSE file for details.