Configuring Symfony (and Environments)

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

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

Every Symfony application consists of a collection of bundles that add useful tools (services) to your project. Each bundle can be customized via configuration files that live - by default - in the app/config directory.

Configuration: `config.yml`

The main configuration file is called config.yml:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        # app/config/config.yml
imports:
    - { resource: parameters.yml }
    - { resource: security.yml }
    - { resource: services.yml }

framework:
    secret:          '%secret%'
    router:          { resource: '%kernel.project_dir%/app/config/routing.yml' }
    # ...

# Twig Configuration
twig:
    debug:            '%kernel.debug%'
    strict_variables: '%kernel.debug%'

# ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
        <!-- 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"
    xmlns:twig="http://symfony.com/schema/dic/twig"
    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
        http://symfony.com/schema/dic/twig
        https://symfony.com/schema/dic/twig/twig-1.0.xsd">

    <imports>
        <import resource="parameters.yml"/>
        <import resource="security.yml"/>
        <import resource="services.yml"/>
    </imports>

    <framework:config secret="%secret%">
        <framework:router resource="%kernel.project_dir%/app/config/routing.xml"/>
        <!-- ... -->
    </framework:config>

    <!-- Twig Configuration -->
    <twig:config debug="%kernel.debug%" strict-variables="%kernel.debug%"/>

    <!-- ... -->
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        // app/config/config.php
$this->import('parameters.yml');
$this->import('security.yml');
$this->import('services.yml');

$container->loadFromExtension('framework', [
    'secret' => '%secret%',
    'router' => [
        'resource' => '%kernel.project_dir%/app/config/routing.php',
    ],
    // ...
]);

// Twig Configuration
$container->loadFromExtension('twig', [
    'debug' => '%kernel.debug%',
    'strict_variables' => '%kernel.debug%',
]);

// ...
    

Most top-level keys - like framework and twig - are configuration for a specific bundle (i.e. FrameworkBundle and TwigBundle).

Throughout the documentation, all configuration examples will be shown in three formats (YAML, XML and PHP). YAML is used by default, but you can choose whatever you like best. There is no performance difference:

The YAML Format: Simple, clean and readable;
XML: More powerful than YAML at times & supports IDE autocompletion;
PHP: Very powerful but less readable than standard configuration formats.

Configuration Reference & Dumping

There are two ways to know what keys you can configure:

Use the Reference Section;
Use the config:dump-reference command.

For example, if you want to configure something in Twig, you can see an example dump of all available configuration options by running:

        1
        $ php bin/console config:dump-reference twig
    

The imports Key: Loading other Configuration Files

Symfony's main configuration file is app/config/config.yml. But, for organization, it also loads other configuration files via its imports key:

        1
2
3
4
5
6
        # app/config/config.yml
imports:
    - { resource: parameters.yml }
    - { resource: security.yml }
    - { resource: services.yml }
# ...
    

        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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <imports>
        <import resource="parameters.yml"/>
        <import resource="security.yml"/>
        <import resource="services.yml"/>
    </imports>

    <!-- ... -->
</container>
    

        1
2
3
4
5
6
        // app/config/config.php
$this->import('parameters.yml');
$this->import('security.yml');
$this->import('services.yml');

// ...
    

The imports key works a lot like the PHP include() function: the contents of parameters.yml, security.yml and services.yml are read and loaded. You can also load XML files or PHP files.

Tip

If your application uses unconventional file extensions (for example, your YAML files have a .res extension) you can set the file type explicitly with the type option:

        1
2
3
4
        # app/config/config.yml
imports:
    - { resource: parameters.res, type: yml }
    # ...
    

        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.res" type="yml"/>
        <!-- ... -->
    </imports>
</container>
    

        1
2
3
        // app/config/config.php
$this->import('parameters.res', 'yml');
// ...
    

The parameters Key: Parameters (Variables)

Another special key is called parameters: it's used to define variables that can be referenced in any other configuration file. For example, in config.yml, a locale parameter is defined and then referenced below under the framework key:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        # app/config/config.yml
# ...

parameters:
    locale: en

framework:
    # ...

    # any string surrounded by two % is replaced by that parameter value
    default_locale:  "%locale%"

# ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        <!-- 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="locale">en</parameter>
    </parameters>

    <framework:config default-locale="%locale%">
        <!-- ... -->
    </framework:config>

    <!-- ... -->
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // app/config/config.php
// ...

$container->setParameter('locale', 'en');

$container->loadFromExtension('framework', [
    'default_locale' => '%locale%',
    // ...
]);

// ...
    

You can define whatever parameter names you want under the parameters key of any configuration file. To reference a parameter, surround its name with two percent signs - e.g. %locale%.

The Special `parameters.yml` File

On the surface, parameters.yml is just like any other configuration file: it is imported by config.yml and defines several parameters:

        1
2
3
4
        parameters:
    # ...
    database_user:      root
    database_password:  ~
    

Not surprisingly, these are referenced from inside of config.yml and help to configure DoctrineBundle and other parts of Symfony:

        1
2
3
4
5
6
7
        # app/config/config.yml
doctrine:
    dbal:
        driver:   pdo_mysql
        # ...
        user:     '%database_user%'
        password: '%database_password%'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- 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
            driver="pdo_mysql"

            user="%database_user%"
            password="%database_password%"/>
    </doctrine:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
        // app/config/config.php
$container->loadFromExtension('doctrine', [
    'dbal' => [
        'driver'   => 'pdo_mysql',
        // ...

        'user'     => '%database_user%',
        'password' => '%database_password%',
    ],
]);
    

But the parameters.yml file is special: it defines the values that usually change on each server. For example, the database credentials on your local development machine might be different from your workmates. That's why this file is not committed to the shared repository and is only stored on your machine.

Because of that, parameters.yml is not committed to your version control. In fact, the .gitignore file that comes with Symfony prevents it from being committed.

However, a parameters.yml.dist file is committed (with dummy values). This file isn't read by Symfony: it's just a reference so that Symfony knows which parameters need to be defined in the parameters.yml file. If you add or remove keys to parameters.yml, add or remove them from parameters.yml.dist too so both files are always in sync.

When you install an existing Symfony project, you will need to create the parameters.yml file using the committed parameters.yml.dist file as a reference. To help with this, after you run composer install, a Symfony script will automatically create this file by interactively asking you to supply the value for each parameter defined in parameters.yml.dist. For more details - or to remove or control this behavior - see the Incenteev Parameter Handler documentation.

Environments & the Other Config Files

You have just one app, but whether you realize it or not, you need it to behave differently at different times:

While developing, you want your app to log everything and expose nice debugging tools;
After deploying to production, you want that same app to be optimized for speed and only log errors.

How can you make one application behave in two different ways? With environments.

You've probably already been using the dev environment without even knowing it. After you deploy, you'll use the prod environment.

To learn more about how to execute and control each environment, see How to Master and Create new Environments.

Keep Going!

Congratulations! You've tackled the basics in Symfony. Next, learn about each part of Symfony individually by following the guides. Check out:

And the many other topics.

Learn more

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version

Symfony Code Performance Profiling

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).