Configuring Symfony

Configuration Files

Symfony applications are configured with the files stored in the config/directory, which has this default structure:

your-project/
├─ config/
│  ├─ packages/
│  ├─ bundles.php
│  ├─ routes.yaml
│  └─ services.yaml
├─ ...

The routes.yaml file defines the routing configuration;the services.yaml file configures the services of theservice container; the bundles.php file enables/disables packages in your application.

You'll be working most in the config/packages/ directory. This directorystores the configuration of every package installed in your application.Packages (also called "bundles" in Symfony and "plugins/modules" in otherprojects) add ready-to-use features to your projects.

When using Symfony Flex, which is enabled by default inSymfony applications, packages update the bundles.php file and create newfiles in config/packages/ automatically during their installation. Forexample, this is the default file created by the "API Platform" package:

# config/packages/api_platform.yaml
api_platform:
    mapping:
        paths: ['%kernel.project_dir%/src/Entity']

Splitting the configuration into lots of small files is intimidating for someSymfony newcomers. However, you'll get used to them quickly and you rarely needto change these files after package installation

Tip

To learn about all the available configuration options, check out theSymfony Configuration Reference or run theconfig:dump-reference command.

Configuration Formats

Unlike other frameworks, Symfony doesn't impose you a specific format toconfigure your applications. Symfony lets you choose between YAML, XML and PHPand throughout the Symfony documentation, all configuration examples will beshown in these three formats.

There isn't any practical difference between formats. In fact, Symfonytransforms and caches all of them into PHP before running the application, sothere's not even any performance difference between them.

YAML is used by default when installing packages because it's concise and veryreadable. These are the main advantages and disadvantages of each format:

• YAML: simple, clean and readable, but not all IDEs support autocompletionand validation for it. Learn the YAML syntax;
• XML:autocompleted/validated by most IDEs and is parsed natively by PHP,but sometimes it generates too verbose configuration. Learn the XML syntax;
• PHP: very powerful and it allows to create dynamic configuration, but theresulting configuration is less readable than the other formats.

Importing Configuration Files

Symfony loads configuration files using the Config component, which provides advanced features such as importing otherconfiguration files, even if they use a different format:

• YAML

# config/services.yaml
imports:
    - { resource: 'legacy_config.php' }
    # ignore_errors silently discards errors if the loaded file doesn't exist
    - { resource: 'my_config_file.xml', ignore_errors: true }
    # glob expressions are also supported to load multiple files
    - { resource: '/etc/myapp/*.yaml' }
 
# ...

• XML

<!-- 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"
    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">
 
    <imports>
        <import resource="legacy_config.php"/>
        <!-- ignore_errors silently discards errors if the loaded file doesn't exist -->
        <import resource="my_config_file.yaml" ignore-errors="true"/>
        <!-- glob expressions are also supported to load multiple files -->
        <import resource="/etc/myapp/*.yaml"/>
    </imports>
 
    <!-- ... -->
</container>

• PHP

// config/services.php
$loader->import('legacy_config.xml');
// the third optional argument of import() is 'ignore_errors', which
// silently discards errors if the loaded file doesn't exist
$loader->import('my_config_file.yaml', null, true);
// glob expressions are also supported to load multiple files
$loader->import('/etc/myapp/*.yaml');
 
// ...

Configuration Parameters

Sometimes the same configuration value is used in several configuration files.Instead of repeating it, you can define it as a "parameter", which is like areusable configuration value. By convention, parameters are defined under theparameters key in the config/services.yaml file:

• YAML

# config/services.yaml
parameters:
    # the parameter name is an arbitrary string (the 'app.' prefix is recommended
    # to better differentiate your parameters from Symfony parameters).
    app.admin_email: '[email protected]'
 
    # boolean parameters
    app.enable_v2_protocol: true
 
    # array/collection parameters
    app.supported_locales: ['en', 'es', 'fr']
 
    # binary content parameters (encode the contents with base64_encode())
    app.some_parameter: !!binary VGhpcyBpcyBhIEJlbGwgY2hhciAH
 
    # PHP constants as parameter values
    app.some_constant: !php/const GLOBAL_CONSTANT
    app.another_constant: !php/const App\Entity\BlogPost::MAX_ITEMS
 
# ...

• XML

<!-- 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>
        <!-- the parameter name is an arbitrary string (the 'app.' prefix is recommended
             to better differentiate your parameters from Symfony parameters). -->
        <parameter key="app.admin_email">[email protected]</parameter>
 
        <!-- boolean parameters -->
        <parameter key="app.enable_v2_protocol">true</parameter>
        <!-- if you prefer to store the boolean value as a string in the parameter -->
        <parameter key="app.enable_v2_protocol" type="string">true</parameter>
 
        <!-- array/collection parameters -->
        <parameter key="app.supported_locales" type="collection">
            <parameter>en</parameter>
            <parameter>es</parameter>
            <parameter>fr</parameter>
        </parameter>
 
        <!-- binary content parameters (encode the contents with base64_encode()) -->
        <parameter key="app.some_parameter" type="binary">VGhpcyBpcyBhIEJlbGwgY2hhciAH</parameter>
 
        <!-- PHP constants as parameter values -->
        <parameter key="app.some_constant" type="constant">GLOBAL_CONSTANT</parameter>
        <parameter key="app.another_constant" type="constant">App\Entity\BlogPost::MAX_ITEMS</parameter>
    </parameters>
 
    <!-- ... -->
</container>

• PHP

// config/services.php
// the parameter name is an arbitrary string (the 'app.' prefix is recommended
// to better differentiate your parameters from Symfony parameters).
$container->setParameter('app.admin_email', '[email protected]');
 
// boolean parameters
$container->setParameter('app.enable_v2_protocol', true);
 
// array/collection parameters
$container->setParameter('app.supported_locales', ['en', 'es', 'fr']);
 
// binary content parameters (use the PHP escape sequences)
$container->setParameter('app.some_parameter', 'This is a Bell char: \x07');
 
// PHP constants as parameter values
use App\Entity\BlogPost;
 
$container->setParameter('app.some_constant', GLOBAL_CONSTANT);
$container->setParameter('app.another_constant', BlogPost::MAX_ITEMS);
 
// ...

Caution

When using XML configuration, the values between <parameter> tags arenot trimmed. This means that the value of the following parameter will be'\n something@example.com\n':

<parameter key="app.admin_email">
    [email protected]
</parameter>

Once defined, you can reference this parameter value from any otherconfiguration file using a special syntax: wrap the parameter name in two %(e.g. %app.admin_email%):

• YAML

# config/packages/some_package.yaml
some_package:
    # any string surrounded by two % is replaced by that parameter value
    email_address: '%app.admin_email%'
 
    # ...

• XML

<!-- config/packages/some_package.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">
 
    <!-- any string surrounded by two % is replaced by that parameter value -->
    <some-package:config email-address="%app.admin_email%">
        <!-- ... -->
    </some-package:config>
</container>

• PHP

// config/packages/some_package.php
$container->loadFromExtension('some_package', [
    // any string surrounded by two % is replaced by that parameter value
    'email_address' => '%app.admin_email%',
 
    // ...
]);

Note

If some parameter value includes the % character, you need to escape itby adding another % so Symfony doesn't consider it a reference to aparameter name:

• YAML

# config/services.yaml
parameters:
    # Parsed as 'https://symfony.com/?foo=%s&bar=%d'
    url_pattern: 'https://symfony.com/?foo=%%s&bar=%%d'

• XML

<!-- config/services.xml -->
<parameters>
    <parameter key="url_pattern">http://symfony.com/?foo=%%s&amp;bar=%%d</parameter>
</parameters>

• PHP

// config/services.php
$container->setParameter('url_pattern', 'http://symfony.com/?foo=%%s&bar=%%d');

Note

Due to the way in which parameters are resolved, you cannot use themto build paths in imports dynamically. This means that something likethe following doesn't work:

• YAML

# config/services.yaml
imports:
    - { resource: '%kernel.project_dir%/somefile.yaml' }

• XML

<!-- 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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">
 
    <imports>
        <import resource="%kernel.project_dir%/somefile.yaml"/>
    </imports>
</container>

• PHP

// config/services.php
$loader->import('%kernel.project_dir%/somefile.yaml');

Configuration parameters are very common in Symfony applications. Some packageseven define their own parameters (e.g. when installing the translation package,a new locale parameter is added to the config/services.yaml file).

Later in this article you can read how toref:get configuration parameters in controllers and services <configuration-accessing-parameters>.

Configuration Environments

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

• While developing, you want to log everything and expose nice debugging tools;
• After deploying to production, you want that same application to beoptimized for speed and only log errors.The files stored in config/packages/ are used by Symfony to configure theapplication services. In other words, you can changethe application behavior by changing which configuration files are loaded.That's the idea of Symfony's configuration environments.

A typical Symfony application begins with three environments: dev (for localdevelopment), prod (for production servers) and test (forautomated tests). When running the application, Symfony loadsthe configuration files in this order (the last files can override the valuesset in the previous ones):

• config/packages/.yaml (and .xml and .php files too);
• config/packages/<environment-name>/.yaml (and .xml and .php files too);

• config/packages/services.yaml (and services.xml and services.php files too);Take the framework package, installed by default, as an example:

• First, config/packages/framework.yaml is loaded in all environments andit configures the framework with some options;

• In the prod environment, nothing extra will be set as there is noconfig/packages/prod/framework.yaml file;
• In the dev environment, there is no file either (config/packages/dev/framework.yaml does not exist).
• In the test environment, the config/packages/test/framework.yaml fileis loaded to override some of the settings previously configured inconfig/packages/framework.yaml.In reality, each environment differs only somewhat from others. This means thatall environments share a large base of common configurations, which is put infiles directly in the config/packages/ directory.

See the configureContainer() method ofthe Kernel class tolearn everything about the loading order of configuration files.

Selecting the Active Environment

Symfony applications come with a file called .env located at the projectroot directory. This file is used to define the value of environment variablesand it's explained in detail later in this article.

Open the .env file (or better, the .env.local file if you created one)and edit the value of the APP_ENV variable to change the environment inwhich the application runs. For example, to run the application in production:

# .env (or .env.local)
APP_ENV=prod

This value is used both for the web and for the console commands. However, youcan override it for commands by setting the APP_ENV value before running them:

# Use the environment defined in the .env file
$ php bin/console command_name
 
# Ignore the .env file and run this command in production
$ APP_ENV=prod php bin/console command_name

Creating a New Environment

The default three environments provided by Symfony are enough for most projects,but you can define your own environments too. For example, this is how you candefine a staging environment where the client can test the project beforegoing to production:

• Create a configuration directory with the same name as the environment (inthis case, config/packages/staging/);
• Add the needed configuration files in config/packages/staging/ todefine the behavior of the new environment. Symfony loads first the files inconfig/packages/*.yaml, so you must only configure the differences withthose files;
• Select the staging environment using the APP_ENV env var as explainedin the previous section.

Tip

It's common for environments to be similar between each other, so you canuse symbolic links between config/packages/<environment-name>/directories to reuse the same configuration.

Configuration Based on Environment Variables

Using environment variables (or "env vars" for short) is a common practice toconfigure options that depend on where the application is run (e.g. the databasecredentials are usually different in production and in your local machine).

Instead of defining those as regular options, you can define them as environmentvariables and reference them in the configuration files using the special syntax%env(ENV_VAR_NAME)%. The values of these options are resolved at runtime(only once per request, to not impact performance).

This example shows how to configure the database connection using an env var:

• YAML

# config/packages/doctrine.yaml
doctrine:
    dbal:
        # by convention the env var names are always uppercase
        url: '%env(DATABASE_URL)%'
    # ...

• XML

<!-- config/packages/doctrine.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>
        <!-- by convention the env var names are always uppercase -->
        <doctrine:dbal url="%env(DATABASE_URL)%"/>
    </doctrine:config>
 
</container>

• PHP

// config/packages/doctrine.php
$container->loadFromExtension('doctrine', [
    'dbal' => [
        // by convention the env var names are always uppercase
        'url' => '%env(DATABASE_URL)%',
    ]
]);

The next step is to define the value of those env vars in your shell, your webserver, etc. This is explained in the following sections, but to protect yourapplication from undefined env vars, you can give them a default value using the.env file:

# .env
DATABASE_URL=sqlite:///%kernel.project_dir%/var/data.db

The values of env vars can only be strings, but Symfony includes someenv var processors to transformtheir contents (e.g. to turn a string value into an integer).

In order to define the actual values of env vars, Symfony proposes differentsolutions depending if the application is running in production or in your localdevelopment machine.

Independent from the way you set environment variables, you may need to run thedebug:container command with the —env-vars option to verify that theyare defined and have the expected values:

$ php bin/console debug:container --env-vars
 
---------------- ----------------- ---------------------------------------------
 Name             Default value     Real value
---------------- ----------------- ---------------------------------------------
 APP_SECRET       n/a               "471a62e2d601a8952deb186e44186cb3"
 FOO              "[1, "2.5", 3]"   n/a
 BAR              null              n/a
---------------- ----------------- ---------------------------------------------
 
# you can also filter the list of env vars by name:
$ php bin/console debug:container --env-vars foo
 
# run this command to show all the details for a specific env var:
$ php bin/console debug:container --env-var=FOO

New in version 4.3: The option to debug environment variables was introduced in Symfony 4.3.

Configuring Environment Variables in Development

Instead of defining env vars in your shell or your web server, Symfony proposesa convenient way of defining them in your local machine based on a file called.env (with a leading dot) located at the root of your project.

The .env file is read and parsed on every request and its env vars are addedto the $_ENV PHP variable. The existing env vars are never overwritten bythe values defined in .env, so you can combine both.

This is for example the content of the .env file to define the value of theDATABASE_URL env var shown earlier in this article:

# .env
DATABASE_URL="mysql://db_user:[email protected]:3306/db_name"

In addition to your own env vars, this .env file also contains the env varsdefined by the third-party packages installed in your application (they areadded automatically by Symfony Flex when installing packages).

Configuring Environment Variables in Production

In production, the .env files are also parsed and loaded on each request soyou can override the env vars already defined in the server. In order to improveperformance, you can run the dump-env command (available when usingSymfony Flex 1.2 or later).

This command parses all the .env files once and compiles their contents intoa new PHP-optimized file called .env.local.php. From that moment, Symfonywill load the parsed file instead of parsing the .env files again:

$ composer dump-env prod

Tip

Update your deployment tools/workflow to run the dump-env command aftereach deploy to improve the application performance.

Creating .env files is the easiest way of using env vars in Symfonyapplications. However, you can also configure real env vars in your servers andoperating systems.

Tip

SymfonyCloud, the cloud service optimized for Symfony applications, definessome utilities to manage env vars in production.

Caution

Beware that dumping the contents of the $_SERVER and $_ENV variablesor outputting the phpinfo() contents will display the values of theenvironment variables, exposing sensitive information such as the databasecredentials.

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

Managing Multiple .env Files

The .env file defines the default values for all env vars. However, it'scommon to override some of those values depending on the environment (e.g. touse a different database for tests) or depending on the machine (e.g. to use adifferent OAuth token on your local machine while developing).

That's why you can define multiple .env files to override env vars. Thefollowing list shows the files loaded in all environments. The .env file isthe only mandatory file and each file content overrides the previous one:

• .env: defines the default values of the env vars needed by the application;
• .env.local: defines machine-specific overrides for env vars on allenvironments. This file is not committed to the repository, so these overridesonly apply to the machine which contains the file (your local computer,production server, etc.);
• .env.<environment> (e.g. .env.test): overrides env vars only for someenvironment but for all machines;
• .env.<environment>.local (e.g. .env.test.local): defines machine-specificenv vars overrides only for some environment. It's similar to .env.local,but the overrides only apply to some particular environment.

Note

The real environment variables defined in the server always win over theenv vars created by the .env files.

The .env and .env.<environment> files should be committed to the sharedrepository because they are the same for all developers and machines. However,the env files ending in .local (.env.local and .env.<environment>.local)should not be committed because only you will use them. In fact, the.gitignore file that comes with Symfony prevents them from being committed.

Caution

Applications created before November 2018 had a slightly different system,involving a .env.dist file. For information about upgrading, see:Nov 2018 Changes to .env & How to Update.

Accessing Configuration Parameters

Controllers and services can access all the configuration parameters. Thisincludes both the parameters defined by yourselfand the parameters created by packages/bundles. Run the following command to seeall the parameters that exist in your application:

$ php bin/console debug:container --parameters

In controllers extending from the AbstractController,use the getParameter() helper:

// src/Controller/UserController.php
namespace App\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
class UserController extends AbstractController
{
    // ...
 
    public function index()
    {
        $projectDir = $this->getParameter('kernel.project_dir');
        $adminEmail = $this->getParameter('app.admin_email');
 
        // ...
    }
}

In services and controllers not extending from AbstractController, injectthe parameters as arguments of their constructors. You must inject themexplicitly because service autowiringdoesn't work for parameters:

• YAML

# config/services.yaml
parameters:
    app.contents_dir: '...'
 
services:
    App\Service\MessageGenerator:
        arguments:
            $contentsDir: '%app.contents_dir%'

• XML

<!-- 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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">
 
    <parameters>
        <parameter key="app.contents_dir">...</parameter>
    </parameters>
 
    <services>
        <service id="App\Service\MessageGenerator">
            <argument key="$contentsDir">%app.contents_dir%</argument>
        </service>
    </services>
</container>

• PHP

// config/services.php
use App\Service\MessageGenerator;
use Symfony\Component\DependencyInjection\Reference;
 
$container->setParameter('app.contents_dir', '...');
 
$container->getDefinition(MessageGenerator::class)
    ->setArgument('$contentsDir', '%app.contents_dir%');

If you inject the same parameters over and over again, use instead theservices._defaults.bind option. The arguments defined in that option areinjected automatically whenever a service constructor or controller actiondefine an argument with that exact name. For example, to inject the value of thekernel.project_dir parameterwhenever a service/controller defines a $projectDir argument, use this:

• YAML

# config/services.yaml
services:
    _defaults:
        bind:
            # pass this value to any $projectDir argument for any service
            # that's created in this file (including controller arguments)
            $projectDir: '%kernel.project_dir%'
 
    # ...

• XML

<!-- 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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">
 
    <services>
        <defaults autowire="true" autoconfigure="true" public="false">
            <!-- pass this value to any $projectDir argument for any service
                 that's created in this file (including controller arguments) -->
            <bind key="$projectDir">%kernel.project_dir%</bind>
        </defaults>
 
        <!-- ... -->
    </services>
</container>

• PHP

// config/services.php
use App\Controller\LuckyController;
use Psr\Log\LoggerInterface;
use Symfony\Component\DependencyInjection\Reference;
 
$container->register(LuckyController::class)
    ->setPublic(true)
    ->setBindings([
        // pass this value to any $projectDir argument for any service
        // that's created in this file (including controller arguments)
        '$projectDir' => '%kernel.project_dir%',
    ])
;

Read the article about binding arguments by name and/or typeto learn more about this powerful feature.

Finally, if some service needs to access to lots of parameters, instead ofinjecting each of them individually, you can inject all the applicationparameters at once by type-hinting any of its constructor arguments with theContainerBagInterface:

// src/Service/MessageGenerator.php
// ...
 
use Symfony\Component\DependencyInjection\ParameterBag\ContainerBagInterface;
 
class MessageGenerator
{
    private $params;
 
    public function __construct(ContainerBagInterface $params)
    {
        $this->params = $params;
    }
 
    public function someMethod()
    {
        // get any container parameter from $this->params, which stores all of them
        $sender = $this->params->get('mailer_sender');
        // ...
    }
}

Keep Going!

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

• Forms
• Databases and the Doctrine ORM
• Service Container
• Security
• Swift Mailer
• LoggingAnd all the other topics related to configuration:

• Nov 2018 Changes to .env & How to Update
• Environment Variable Processors
• Understanding how the Front Controller, Kernel and Environments Work together
• Building your own Framework with the MicroKernelTrait
• How To Create Symfony Applications with Multiple Kernels
• How to Override Symfony's default Directory Structure
• Using Parameters within a Dependency Injection Class