Environment Variable Processors
Edit this pageWarning: You are browsing the documentation for Symfony 4.2, which is no longer maintained.
Read the updated version of this page for Symfony 7.0 (the current stable version).
Environment Variable Processors
Using env vars to configure Symfony applications is a common practice to hide sensitive configuration (e.g. database credentials) and to make your applications truly dynamic.
The main issue of env vars is that their values can only be strings and your
application may need other data types (integer, boolean, etc.). Symfony solves
this problem with "env var processors", which transform the original contents of
the given environment variables. The following example uses the integer
processor to turn the value of the HTTP_PORT
env var into an integer:
1 2 3 4
# config/packages/framework.yaml
framework:
router:
http_port: '%env(int:HTTP_PORT)%'
1 2 3 4 5 6 7 8 9 10 11 12 13 14
<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:router http-port="%env(int:HTTP_PORT)%"/>
</framework:config>
</container>
1 2 3 4 5 6
// config/packages/framework.php
$container->loadFromExtension('framework', [
'router' => [
'http_port' => '%env(int:HTTP_PORT)%',
],
]);
Built-In Environment Variable Processors
Symfony provides the following env var processors:
env(string:FOO)
-
Casts
FOO
to a string: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 11 12 13 14 15 16
<!-- config/packages/framework.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <parameters> <parameter key="env(SECRET)">some_secret</parameter> </parameters> <framework:config secret="%env(string:SECRET)%"/> </container>
1 2 3 4 5
// config/packages/framework.php $container->setParameter('env(SECRET)', 'some_secret'); $container->loadFromExtension('framework', [ 'secret' => '%env(string:SECRET)%', ]);
env(bool:FOO)
-
Casts
FOO
to a bool: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 11 12 13 14 15 16
<!-- config/packages/framework.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <parameters> <parameter key="env(HTTP_METHOD_OVERRIDE)">true</parameter> </parameters> <framework:config http-methode-override="%env(bool:HTTP_METHOD_OVERRIDE)%"/> </container>
1 2 3 4 5
// config/packages/framework.php $container->setParameter('env(HTTP_METHOD_OVERRIDE)', 'true'); $container->loadFromExtension('framework', [ 'http_method_override' => '%env(bool:HTTP_METHOD_OVERRIDE)%', ]);
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
: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 11 12 13 14 15 16
<!-- config/packages/security.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:security="http://symfony.com/schema/dic/security" xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd"> <parameters> <parameter key="env(HEALTH_CHECK_METHOD)">Symfony\Component\HttpFoundation\Request::METHOD_HEAD</parameter> </parameters> <security:config> <rule path="^/health-check$" methods="%env(const:HEALTH_CHECK_METHOD)%"/> </security:config> </container>
1 2 3 4 5 6 7 8 9 10
// config/packages/security.php $container->setParameter('env(HEALTH_CHECK_METHOD)', 'Symfony\Component\HttpFoundation\Request::METHOD_HEAD'); $container->loadFromExtension('security', [ 'access_control' => [ [ 'path' => '^/health-check$', 'methods' => '%env(const:HEALTH_CHECK_METHOD)%', ], ], ]);
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 ornull
:1 2 3 4 5
# config/packages/framework.yaml parameters: env(TRUSTED_HOSTS): '["10.0.0.1", "10.0.0.2"]' framework: trusted_hosts: '%env(json:TRUSTED_HOSTS)%'
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<!-- config/packages/framework.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <parameters> <parameter key="env(TRUSTED_HOSTS)">["10.0.0.1", "10.0.0.2"]</parameter> </parameters> <framework:config trusted-hosts="%env(json:TRUSTED_HOSTS)%"/> </container>
1 2 3 4 5
// config/packages/framework.php $container->setParameter('env(TRUSTED_HOSTS)', '["10.0.0.1", "10.0.0.2"]'); $container->loadFromExtension('framework', [ 'trusted_hosts' => '%env(json:TRUSTED_HOSTS)%', ]);
env(resolve:FOO)
-
Replaces the string
FOO
by the value of a config parameter with the same name:1 2 3 4 5 6 7
# config/packages/sentry.yaml parameters: env(HOST): '10.0.0.1' sentry_host: '%env(HOST)%' env(SENTRY_DSN): 'http://%sentry_host%/project' sentry: dsn: '%env(resolve:SENTRY_DSN)%'
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<!-- config/packages/sentry.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd"> <parameters> <parameter key="env(HOST)">10.0.0.1</parameter> <parameter key="sentry_host">%env(HOST)%</parameter> <parameter key="env(SENTRY_DSN)">http://%sentry_host%/project</parameter> </parameters> <sentry:config dsn="%env(resolve:SENTRY_DSN)%"/> </container>
1 2 3 4 5 6 7
// config/packages/sentry.php $container->setParameter('env(HOST)', '10.0.0.1'); $container->setParameter('sentry_host', '%env(HOST)%'); $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:1 2 3 4
parameters: env(TRUSTED_HOSTS): "10.0.0.1, 10.0.0.2" framework: trusted_hosts: '%env(csv:TRUSTED_HOSTS)%'
env(file:FOO)
-
Returns the contents of a file whose path is the value of the
FOO
env var:1 2 3 4 5
# config/packages/framework.yaml parameters: env(AUTH_FILE): '../config/auth.json' google: auth: '%env(file:AUTH_FILE)%'
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<!-- config/packages/framework.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <parameters> <parameter key="env(AUTH_FILE)">../config/auth.json</parameter> </parameters> <google auth="%env(file:AUTH_FILE)%"/> </container>
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(key:FOO:BAR)
-
Retrieves the value associated with the key
FOO
from the array whose contents are stored in theBAR
env var: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 4 5 6 7 8 9 10 11 12 13 14 15
<!-- config/services.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <parameters> <parameter key="env(SECRETS_FILE)">/opt/application/.secrets.json</parameter> <parameter key="database_password">%env(key:database_password:json:file:SECRETS_FILE)%</parameter> </parameters> </container>
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)%');
It is also possible to combine any number of processors:
1 2 3 4 5 6 7 8
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)%'
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($prefix, $name, \Closure $getEnv)
{
$env = $getEnv($name);
return strtolower($env);
}
public static function getProvidedTypes()
{
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.