Symfony
sponsored by SensioLabs
Menu
  • About
  • Documentation
  • Screencasts
  • Cloud
  • Certification
  • Community
  • Businesses
  • News
  • Download
  1. Home
  2. Documentation
  3. Configuration
  4. How to Set external Parameters in the Service Container
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud
Search by Algolia

Table of Contents

  • Environment Variables
  • Environment Variable Processors
    • Custom Environment Variable Processors
  • Constants
  • Miscellaneous Configuration

How to Set external Parameters in the Service Container

Edit this page

Warning: You are browsing the documentation for Symfony 3.4, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

How to Set external Parameters in the Service Container

In the article Configuring Symfony (and Environments), you learned how to manage your application configuration. At times, it may benefit your application to store certain credentials outside of your project code. Database configuration is one such example. The flexibility of the Symfony service container allows you to do this.

Environment Variables

3.2

env() parameters were introduced in Symfony 3.2.

You can reference environment variables by using special parameters named after the variables you want to use enclosed between env(). Their actual values will be resolved at runtime (once per request), so that dumped containers can be reconfigured dynamically even after being compiled.

For example, if you want to use the value of the DATABASE_HOST environment variable in your service container configuration, you can reference it using %env(DATABASE_HOST)% in your configuration files:

  • YAML
  • XML
  • PHP
1
2
3
4
# app/config/config.yml
doctrine:
    dbal:
        host: '%env(DATABASE_HOST)%'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!-- app/config/config.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:doctrine="http://symfony.com/schema/dic/doctrine"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/doctrine
        https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">

    <doctrine:config>
        <doctrine:dbal host="%env(DATABASE_HOST)%"/>
    </doctrine:config>

</container>
1
2
3
4
5
6
// app/config/config.php
$container->loadFromExtension('doctrine', [
    'dbal' => [
        'host' => '%env(DATABASE_HOST)%',
    ],
]);

You can also give the env() parameters a default value: the default value will be used whenever the corresponding environment variable is not found:

  • YAML
  • XML
  • PHP
1
2
3
4
# app/config/parameters.yml
parameters:
    database_host: '%env(DATABASE_HOST)%'
    env(DATABASE_HOST): localhost
1
2
3
4
5
6
7
8
9
10
11
12
<!-- app/config/parameters.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="database_host">%env(DATABASE_HOST)%</parameter>
        <parameter key="env(DATABASE_HOST)">localhost</parameter>
    </parameters>
</container>
1
2
3
// app/config/parameters.php
$container->setParameter('database_host', '%env(DATABASE_HOST)%');
$container->setParameter('env(DATABASE_HOST)', 'localhost');

Setting environment variables is generally done at the web server level or in the terminal. If you're using Apache, nginx or just the console, you can use e.g. one of the following:

  • Apache
  • Nginx
  • Bash
1
2
3
4
5
6
<VirtualHost *:80>
    # ...

    SetEnv DATABASE_USER user
    SetEnv DATABASE_PASSWORD secret
</VirtualHost>
1
2
fastcgi_param DATABASE_USER user;
fastcgi_param DATABASE_PASSWORD secret;
1
2
$ export DATABASE_USER=user
$ export DATABASE_PASSWORD=secret

Tip

3.3

The support of the special SYMFONY__ environment variables was deprecated in Symfony 3.3 and will be removed in 4.0. Instead of using those variables, define regular environment variables and get their values using the %env(...)% syntax in your config files.

You can also define the default value of any existing parameters using special environment variables named after their corresponding parameter prefixed with SYMFONY__ after replacing dots by double underscores (e.g. SYMFONY__KERNEL__CHARSET to set the default value of the kernel.charset parameter). These default values are resolved when compiling the service container and won't change at runtime once dumped.

The values of the env vars are also exposed in the web interface of the Symfony profiler. In practice this shouldn't be a problem because the web profiler must never be enabled in production.

Environment Variable Processors

3.4

Environment variable processors were introduced in Symfony 3.4.

The values of environment variables are considered strings by default. However, your code may expect other data types, like integers or booleans. Symfony solves this problem with processors, which modify the 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:

  • YAML
  • XML
  • PHP
1
2
3
4
# app/config/config.yml
framework:
    router:
        http_port: '%env(int:HTTP_PORT)%'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<!-- app/config/config.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
// app/config/config.php
$container->loadFromExtension('framework', [
    'router' => [
        'http_port' => '%env(int:HTTP_PORT)%',
    ],
]);

Symfony provides the following env var processors:

env(string:FOO)

Casts FOO to a string:

  • YAML
  • XML
  • PHP
1
2
3
4
5
# app/config/config.yml
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
<!-- app/config/config.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
// app/config/config.php
$container->setParameter('env(SECRET)', 'some_secret');
$container->loadFromExtension('framework', [
    'secret' => '%env(string:SECRET)%',
]);
env(bool:FOO)

Casts FOO to a bool:

  • YAML
  • XML
  • PHP
1
2
3
4
5
# app/config/config.yml
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
<!-- app/config/config.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
// app/config/config.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 constant value named in FOO:

  • YAML
  • XML
  • PHP
1
2
3
4
5
6
7
# app/config/config.yml
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
<!-- app/config/config.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
// app/config/config.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 or null:

  • YAML
  • XML
  • PHP
1
2
3
4
5
# app/config/config.yml
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
<!-- app/config/config.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
// app/config/config.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:

  • YAML
  • XML
  • PHP
1
2
3
4
5
6
7
# app/config/config.yml
parameters:
    env(HOST): '10.0.0.1'
    sentry_host: '%env(HOST)%'
    env(SENTRY_DSN): 'https://%sentry_host%/project'
sentry:
    dsn: '%env(resolve:SENTRY_DSN)%'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:sentry="http://symfony.com/schema/dic/sentry"
    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)">https://%sentry_host%/project</parameter>
    </parameters>

    <sentry:config dsn="%env(resolve:SENTRY_DSN)%"/>
</container>
1
2
3
4
5
6
7
// app/config/config.php
$container->setParameter('env(HOST)', '10.0.0.1');
$container->setParameter('sentry_host', '%env(HOST)%');
$container->setParameter('env(SENTRY_DSN)', 'https://%sentry_host%/project');
$container->loadFromExtension('sentry', [
    'dsn' => '%env(resolve:SENTRY_DSN)%',
]);
env(file:FOO)

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

  • YAML
  • XML
  • PHP
1
2
3
4
5
6
7
8
# app/config/config.yml
parameters:
    env(AUTH_FILE): '../auth.json'

services:
    some_authenticator:
        arguments:
            $auth: '%env(file:AUTH_FILE)%'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<!-- app/config/config.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
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <parameters>
        <parameter key="env(AUTH_FILE)">../auth.json</parameter>
    </parameters>

    <services>
        <service id="some_authenticator">
            <argument key="$auth">"%env(file:AUTH_FILE)%"<argument/>
        <service>
    </services>
</container>
1
2
3
4
5
6
// app/config/config.php
$container->setParameter('env(AUTH_FILE)', __DIR__.'/../auth.json');

$container->register('some_authenticator')
    ->setArgument('$auth', '%env(file:AUTH_FILE)%')
;

It is also possible to combine any number of processors:

1
2
3
4
5
6
7
8
9
10
11
parameters:
    env(AUTH_FILE): "%kernel.project_dir%/config/auth.json"

services:
    some_authenticator:
        arguments:
            # 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 and then, define a service for that class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
class LowercasingEnvVarProcessor implements EnvVarProcessorInterface
{
    private $container;

    public function __construct(ContainerInterface $container)
    {
        $this->container = $container;
    }

    public function getEnv($prefix, $name, \Closure $getEnv)
    {
        $env = $getEnv($name);

        return strtolower($env);
    }

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

Constants

The container also has support for setting PHP constants as parameters. See Introduction to Parameters for more details.

Miscellaneous Configuration

The imports directive can be used to pull in parameters stored elsewhere. Importing a PHP file gives you the flexibility to add whatever is needed in the container. The following imports a file named parameters.php.

  • YAML
  • XML
  • PHP
1
2
3
# app/config/config.yml
imports:
    - { resource: parameters.php }
1
2
3
4
5
6
7
8
9
10
11
12
<!-- app/config/config.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">

    <imports>
        <import resource="parameters.php"/>
    </imports>

</container>
1
2
// app/config/config.php
$loader->import('parameters.php');

Note

A resource file can be one of many types. PHP, XML, YAML, INI, and closure resources are all supported by the imports directive.

In parameters.php, tell the service container the parameters that you wish to set. This is useful when important configuration is in a non-standard format. The example below includes a Drupal database configuration in the Symfony service container:

1
2
3
// app/config/parameters.php
include_once('/path/to/drupal/sites/default/settings.php');
$container->setParameter('drupal.database.url', $db_url);
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
We stand with Ukraine.
Version:
Make sure your project is risk free

Make sure your project is risk free

Measure & Improve Symfony Code Performance

Measure & Improve Symfony Code Performance

↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

Avatar of Andrew Berry, a Symfony contributor

Thanks Andrew Berry for being a Symfony contributor

2 commits • 12 lines changed

View all contributors that help us make Symfony

Become a Symfony contributor

Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

Learn how to contribute

Symfony™ is a trademark of Symfony SAS. All rights reserved.

  • What is Symfony?
    • Symfony at a Glance
    • Symfony Components
    • Case Studies
    • Symfony Releases
    • Security Policy
    • Logo & Screenshots
    • Trademark & Licenses
    • symfony1 Legacy
  • Learn Symfony
    • Symfony Docs
    • Symfony Book
    • Reference
    • Bundles
    • Best Practices
    • Training
    • eLearning Platform
    • Certification
  • Screencasts
    • Learn Symfony
    • Learn PHP
    • Learn JavaScript
    • Learn Drupal
    • Learn RESTful APIs
  • Community
    • SymfonyConnect
    • Support
    • How to be Involved
    • Code of Conduct
    • Events & Meetups
    • Projects using Symfony
    • Downloads Stats
    • Contributors
    • Backers
  • Blog
    • Events & Meetups
    • A week of symfony
    • Case studies
    • Cloud
    • Community
    • Conferences
    • Diversity
    • Documentation
    • Living on the edge
    • Releases
    • Security Advisories
    • SymfonyInsight
    • Twig
    • SensioLabs
  • Services
    • SensioLabs services
    • Train developers
    • Manage your project quality
    • Improve your project performance
    • Host Symfony projects
    Deployed on
Follow Symfony
Search by Algolia