Environment Variable Processors

Built-In Environment Variable Processors

Symfony provides the following env var processors:

env(string:FOO)

Casts FOO to a string:

YAML PHP

1
2
3
4
5

# config/packages/framework.yaml
parameters:
    env(SECRET): 'some_secret'
framework:
    secret: '%env(string:SECRET)%'

1
2
3
4
5
6
7
8
9
10

// config/packages/framework.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Config\FrameworkConfig;

return static function (ContainerBuilder $container, FrameworkConfig $framework): void {
    $container->setParameter('env(SECRET)', 'some_secret');
    $framework->secret(env('SECRET')->string());
};

env(bool:FOO)

Casts FOO to a bool (true values are 'true', 'on', 'yes', all numbers except 0 and 0.0 and all numeric strings except '0' and '0.0'; everything else is false):

YAML PHP

1
2
3
4
5

# config/packages/framework.yaml
parameters:
    env(HTTP_METHOD_OVERRIDE): 'true'
framework:
    http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%'

1
2
3
4
5
6
7
8
9
10

// config/packages/framework.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Config\FrameworkConfig;

return static function (ContainerBuilder $container, FrameworkConfig $framework): void {
    $container->setParameter('env(HTTP_METHOD_OVERRIDE)', 'true');
    $framework->httpMethodOverride(env('HTTP_METHOD_OVERRIDE')->bool());
};

env(not:FOO)

Casts FOO to a bool (just as env(bool:...) does) except it returns the inverted value (falsy values are returned as true, truthy values are returned as false):

YAML PHP

1
2
3

# config/services.yaml
parameters:
    safe_for_production: '%env(not:APP_DEBUG)%'

1
2

// config/services.php
$container->setParameter('safe_for_production', '%env(not:APP_DEBUG)%');

env(int:FOO)

Casts FOO to an int.

env(float:FOO)

Casts FOO to a float.

env(const:FOO)

Finds the const value named in FOO:

YAML PHP

1
2
3
4
5
6

# config/packages/security.yaml
parameters:
    env(HEALTH_CHECK_METHOD): 'Symfony\Component\HttpFoundation\Request::METHOD_HEAD'
security:
    access_control:
        - { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' }

1
2
3
4
5
6
7
8
9
10

// config/packages/security.php
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Config\SecurityConfig;

return static function (ContainerBuilder $container, SecurityConfig $security): void {
    $container->setParameter('env(HEALTH_CHECK_METHOD)', 'Symfony\Component\HttpFoundation\Request::METHOD_HEAD');
    $security->accessControl()
        ->path('^/health-check$')
        ->methods([env('HEALTH_CHECK_METHOD')->const()]);
};

env(base64:FOO)

Decodes the content of FOO, which is a base64 encoded string.

env(json:FOO)

Decodes the content of FOO, which is a JSON encoded string. It returns either an array or null:

YAML PHP

1
2
3
4

# config/packages/framework.yaml
parameters:
    env(ALLOWED_LANGUAGES): '["en","de","es"]'
    app_allowed_languages: '%env(json:ALLOWED_LANGUAGES)%'

1
2
3
4
5
6
7
8
9
10

// config/packages/framework.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Config\FrameworkConfig;

return static function (ContainerBuilder $container): void {
    $container->setParameter('env(ALLOWED_LANGUAGES)', '["en","de","es"]');
    $container->setParameter('app_allowed_languages', '%env(json:ALLOWED_LANGUAGES)%');
};

env(resolve:FOO)

If the content of FOO includes container parameters (with the syntax %parameter_name%), it replaces the parameters by their values:

YAML PHP

1
2
3
4
5
6

# config/packages/sentry.yaml
parameters:
    sentry_host: '10.0.0.1'
    env(SENTRY_DSN): 'http://%sentry_host%/project'
sentry:
    dsn: '%env(resolve:SENTRY_DSN)%'

1
2
3
4
5
6

// config/packages/sentry.php
$container->setParameter('sentry_host', '10.0.0.1');
$container->setParameter('env(SENTRY_DSN)', 'http://%sentry_host%/project');
$container->loadFromExtension('sentry', [
    'dsn' => '%env(resolve:SENTRY_DSN)%',
]);

env(csv:FOO)

Decodes the content of FOO, which is a CSV-encoded string:

YAML PHP

1
2
3
4

# config/packages/framework.yaml
parameters:
    env(ALLOWED_LANGUAGES): "en,de,es"
    app_allowed_languages: '%env(csv:ALLOWED_LANGUAGES)%'

1
2
3
4
5
6
7
8
9
10

// config/packages/framework.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Config\FrameworkConfig;

return static function (ContainerBuilder $container): void {
    $container->setParameter('env(ALLOWED_LANGUAGES)', 'en,de,es');
    $container->setParameter('app_allowed_languages', '%env(csv:ALLOWED_LANGUAGES)%');
};

env(shuffle:FOO)

Randomly shuffles values of the FOO env var, which must be an array.

YAML PHP

1
2
3
4
5
6
7

# config/packages/framework.yaml
parameters:
    env(REDIS_NODES): "127.0.0.1:6380,127.0.0.1:6381"
services:
    RedisCluster:
        class: RedisCluster
        arguments: [null, "%env(shuffle:csv:REDIS_NODES)%"]

1
2
3
4
5
6
7

// config/services.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    $container = $containerConfigurator->services()
        ->set(\RedisCluster::class, \RedisCluster::class)->args([null, '%env(shuffle:csv:REDIS_NODES)%']);
};

env(file:FOO)

Returns the contents of a file whose path is the value of the FOO env var:

YAML PHP

1
2
3
4
5

# config/packages/framework.yaml
parameters:
    env(AUTH_FILE): '%kernel.project_dir%/config/auth.json'
google:
    auth: '%env(file:AUTH_FILE)%'

1
2
3
4
5

// config/packages/framework.php
$container->setParameter('env(AUTH_FILE)', '../config/auth.json');
$container->loadFromExtension('google', [
    'auth' => '%env(file:AUTH_FILE)%',
]);

env(require:FOO)

require() the PHP file whose path is the value of the FOO env var and return the value returned from it.

YAML PHP

1
2
3
4
5

# config/packages/framework.yaml
parameters:
    env(PHP_FILE): '%kernel.project_dir%/config/.runtime-evaluated.php'
app:
    auth: '%env(require:PHP_FILE)%'

1
2
3
4
5

// config/packages/framework.php
$container->setParameter('env(PHP_FILE)', '../config/.runtime-evaluated.php');
$container->loadFromExtension('app', [
    'auth' => '%env(require:PHP_FILE)%',
]);

env(trim:FOO)

Trims the content of FOO env var, removing whitespaces from the beginning and end of the string. This is especially useful in combination with the file processor, as it'll remove newlines at the end of a file.

YAML PHP

1
2
3
4
5

# config/packages/framework.yaml
parameters:
    env(AUTH_FILE): '%kernel.project_dir%/config/auth.json'
google:
    auth: '%env(trim:file:AUTH_FILE)%'

1
2
3
4
5

// config/packages/framework.php
$container->setParameter('env(AUTH_FILE)', '../config/auth.json');
$container->loadFromExtension('google', [
    'auth' => '%env(trim:file:AUTH_FILE)%',
]);

env(key:FOO:BAR)

Retrieves the value associated with the key FOO from the array whose contents are stored in the BAR env var:

YAML PHP

1
2
3
4
5

# config/services.yaml
parameters:
    env(SECRETS_FILE): '/opt/application/.secrets.json'
    database_password: '%env(key:database_password:json:file:SECRETS_FILE)%'
    # if SECRETS_FILE contents are: {"database_password": "secret"} it returns "secret"

1
2
3

// config/services.php
$container->setParameter('env(SECRETS_FILE)', '/opt/application/.secrets.json');
$container->setParameter('database_password', '%env(key:database_password:json:file:SECRETS_FILE)%');

env(default:fallback_param:BAR)

Retrieves the value of the parameter fallback_param when the BAR env var is not available:

YAML PHP

1
2
3
4
5

# config/services.yaml
parameters:
    # if PRIVATE_KEY is not a valid file path, the content of raw_key is returned
    private_key: '%env(default:raw_key:file:PRIVATE_KEY)%'
    raw_key: '%env(PRIVATE_KEY)%'

1
2
3
4
5

// config/services.php

// if PRIVATE_KEY is not a valid file path, the content of raw_key is returned
$container->setParameter('private_key', '%env(default:raw_key:file:PRIVATE_KEY)%');
$container->setParameter('raw_key', '%env(PRIVATE_KEY)%');

When the fallback parameter is omitted (e.g. env(default::API_KEY)), then the returned value is null.

env(url:FOO)

Parses an absolute URL and returns its components as an associative array.

1
2

# .env
MONGODB_URL="mongodb://db_user:db_password@127.0.0.1:27017/db_name"

YAML PHP

1
2
3
4
5
6
7
8
9
10
11

# config/packages/mongodb.yaml
mongo_db_bundle:
    clients:
        default:
            hosts:
                - { host: '%env(string:key:host:url:MONGODB_URL)%', port: '%env(int:key:port:url:MONGODB_URL)%' }
            username: '%env(string:key:user:url:MONGODB_URL)%'
            password: '%env(string:key:pass:url:MONGODB_URL)%'
    connections:
        default:
            database_name: '%env(key:path:url:MONGODB_URL)%'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// config/packages/mongodb.php
$container->loadFromExtension('mongodb', [
    'clients' => [
        'default' => [
            'hosts' => [
                [
                    'host' => '%env(string:key:host:url:MONGODB_URL)%',
                    'port' => '%env(int:key:port:url:MONGODB_URL)%',
                ],
            ],
            'username' => '%env(string:key:user:url:MONGODB_URL)%',
            'password' => '%env(string:key:pass:url:MONGODB_URL)%',
        ],
    ],
    'connections' => [
        'default' => [
            'database_name' => '%env(key:path:url:MONGODB_URL)%',
        ],
    ],
]);

Warning

In order to ease extraction of the resource from the URL, the leading / is trimmed from the path component.

env(query_string:FOO)

Parses the query string part of the given URL and returns its components as an associative array.

1
2

# .env
MONGODB_URL="mongodb://db_user:db_password@127.0.0.1:27017/db_name?timeout=3000"

YAML PHP

1
2
3
4
5
6

# config/packages/mongodb.yaml
mongo_db_bundle:
    clients:
        default:
            # ...
            connectTimeoutMS: '%env(int:key:timeout:query_string:MONGODB_URL)%'

1
2
3
4
5
6
7
8
9

// config/packages/mongodb.php
$container->loadFromExtension('mongodb', [
    'clients' => [
        'default' => [
            // ...
            'connectTimeoutMS' => '%env(int:key:timeout:query_string:MONGODB_URL)%',
        ],
    ],
]);

env(enum:FooEnum:BAR)

Tries to convert an environment variable to an actual \BackedEnum value. This processor takes the fully qualified name of the \BackedEnum as an argument:

1
2
3
4
5
6
7
8

// App\Enum\Suit.php
enum Suit: string
{
    case Clubs = 'clubs';
    case Spades = 'spades';
    case Diamonds = 'diamonds';
    case Hearts = 'hearts';
}

YAML PHP

1
2
3

# config/services.yaml
parameters:
    suit: '%env(enum:App\Enum\Suit:CARD_SUIT)%'

1
2

// config/services.php
$container->setParameter('suit', '%env(enum:App\Enum\Suit:CARD_SUIT)%');

The value stored in the CARD_SUIT env var would be a string (e.g. 'spades') but the application will use the enum value (e.g. Suit::Spades).

env(defined:NO_FOO)

Evaluates to true if the env var exists and its value is not '' (an empty string) or null; it returns false otherwise.

YAML PHP

1
2
3

# config/services.yaml
parameters:
    typed_env: '%env(defined:FOO)%'

1
2

// config/services.php
$container->setParameter('typed_env', '%env(defined:FOO)%');

env(urlencode:FOO)

Encodes the content of the FOO env var using the urlencode PHP function. This is especially useful when FOO value is not compatible with DSN syntax.

YAML PHP

1
2
3
4

# config/packages/framework.yaml
parameters:
    env(DATABASE_URL): 'mysql://db_user:foo@b$r@127.0.0.1:3306/db_name'
    encoded_database_url: '%env(urlencode:DATABASE_URL)%'

1
2
3
4
5
6
7
8
9
10

// config/packages/framework.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Config\FrameworkConfig;

return static function (ContainerBuilder $container): void {
    $container->setParameter('env(DATABASE_URL)', 'mysql://db_user:foo@b$r@127.0.0.1:3306/db_name');
    $container->setParameter('encoded_database_url', '%env(urlencode:DATABASE_URL)%');
};

It is also possible to combine any number of processors:

1
2
3
4
5
6
7
8
9

# config/packages/framework.yaml
parameters:
    env(AUTH_FILE): "%kernel.project_dir%/config/auth.json"
google:
    # 1. gets the value of the AUTH_FILE env var
    # 2. replaces the values of any config param to get the config path
    # 3. gets the content of the file stored in that path
    # 4. JSON-decodes the content of the file and returns it
    auth: '%env(json:file:resolve:AUTH_FILE)%'

1
2
3
4
5
6
7
8
9

// config/packages/framework.php
$container->setParameter('env(AUTH_FILE)', '%kernel.project_dir%/config/auth.json');
// 1. gets the value of the AUTH_FILE env var
// 2. replaces the values of any config param to get the config path
// 3. gets the content of the file stored in that path
// 4. JSON-decodes the content of the file and returns it
$container->loadFromExtension('google', [
    'auth' => '%env(json:file:resolve:AUTH_FILE)%',
]);

Custom Environment Variable Processors

It's also possible to add your own processors for environment variables. First, create a class that implements EnvVarProcessorInterface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

use Symfony\Component\DependencyInjection\EnvVarProcessorInterface;

class LowercasingEnvVarProcessor implements EnvVarProcessorInterface
{
    public function getEnv(string $prefix, string $name, \Closure $getEnv): string
    {
        $env = $getEnv($name);

        return strtolower($env);
    }

    public static function getProvidedTypes(): array
    {
        return [
            'lowercase' => 'string',
        ];
    }
}

To enable the new processor in the app, register it as a service and tag it with the container.env_var_processor tag. If you're using the default services.yaml configuration, this is already done for you, thanks to autoconfiguration.

Resolving Environment Variable At Compile Time

Environment variables are resolved at runtime, but you can also resolve them at compile time.