Configuring Symfony

Configuration Formats

Unlike other frameworks, Symfony doesn't impose a specific format on you to configure your applications, but lets you choose between YAML, XML and PHP. Throughout the Symfony documentation, all configuration examples will be shown in these three formats.

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

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

• YAML: simple, clean and readable, but not all IDEs support autocompletion and validation for it. Learn the YAML syntax;
• XML: autocompleted/validated by most IDEs and is parsed natively by PHP, but sometimes it generates configuration considered too verbose. Learn the XML syntax;
• PHP: very powerful and it allows you to create dynamic configuration with arrays or a ConfigBuilder.

Importing Configuration Files

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

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/services.yaml
imports:
    - { resource: 'legacy_config.php' }

    # glob expressions are also supported to load multiple files
    - { resource: '/etc/myapp/*.yaml' }

    # ignore_errors: not_found silently discards errors if the loaded file doesn't exist
    - { resource: 'my_config_file.xml', ignore_errors: not_found }
    # ignore_errors: true silently discards all errors (including invalid code and not found)
    - { resource: 'my_other_config_file.xml', ignore_errors: true }

# ...

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

<!-- 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"/>
        <!-- glob expressions are also supported to load multiple files -->
        <import resource="/etc/myapp/*.yaml"/>

        <!-- ignore-errors="not_found" silently discards errors if the loaded file doesn't exist -->
        <import resource="my_config_file.yaml" ignore-errors="not_found"/>
        <!-- ignore-errors="true" silently discards all errors (including invalid code and not found) -->
        <import resource="my_other_config_file.yaml" ignore-errors="true"/>
    </imports>

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

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

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

return static function (ContainerConfigurator $container): void {
    $container->import('legacy_config.php');

    // glob expressions are also supported to load multiple files
    $container->import('/etc/myapp/*.yaml');

    // the third optional argument of import() is 'ignore_errors'
    // 'ignore_errors' set to 'not_found' silently discards errors if the loaded file doesn't exist
    $container->import('my_config_file.yaml', null, 'not_found');
    // 'ignore_errors' set to true silently discards all errors (including invalid code and not found)
    $container->import('my_config_file.yaml', null, true);
};

// ...

Selecting the Active Environment

Symfony applications come with a file called .env located at the project root directory. This file is used to define the value of environment variables and 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 in which the application runs. For example, to run the application in production:

1
2

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

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

1
2
3
4
5

# 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 can define a staging environment where the client can test the project before going to production:

1. Create a configuration directory with the same name as the environment (in this case, config/packages/staging/);
2. Add the needed configuration files in config/packages/staging/ to define the behavior of the new environment. Symfony loads the config/packages/*.yaml files first, so you only need to configure the differences to those files;
3. Select the staging environment using the APP_ENV env var as explained in the previous section.

Instead of creating new environments, you can use environment variables as explained in the following section. This way you can use the same application and environment (e.g. prod) but change its behavior thanks to the configuration based on environment variables (e.g. to run the application in different scenarios: staging, quality assurance, client review, etc.)

Configuring Environment Variables in .env Files

Instead of defining env vars in your shell or your web server, Symfony provides a convenient way to define them inside a .env (with a leading dot) file located at the root of your project.

The .env file is read and parsed on every request and its env vars are added to the $_ENV & $_SERVER PHP variables. Any existing env vars are never overwritten by the values defined in .env, so you can combine both.

For example, to define the DATABASE_URL env var shown earlier in this article, you can add:

1
2

# .env
DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"

This file should be committed to your repository and (due to that fact) should only contain "default" values that are good for local development. This file should not contain production values.

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

1
2
3

# database credentials
DB_USER=root
DB_PASS=pass # this is the secret password

1
2

DB_USER=root
DB_PASS=${DB_USER}pass # include the user as a password prefix

1
2

DB_USER=
DB_PASS=${DB_USER:-root}pass # results in DB_PASS=rootpass

1

START_TIME=$(date)

1

$ source .env

Overriding Environment Values via .env.local

If you need to override an environment value (e.g. to a different value on your local machine), you can do that in a .env.local file:

1
2

# .env.local
DATABASE_URL="mysql://root:@127.0.0.1:3306/my_database_name"

This file should be ignored by git and should not be committed to your repository. Several other .env files are available to set environment variables in just the right situation:

• .env: defines the default values of the env vars needed by the application;
• .env.local: overrides the default values for all environments but only on the machine which contains the file. This file should not be committed to the repository and it's ignored in the test environment (because tests should produce the same results for everyone);
• .env.<environment> (e.g. .env.test): overrides env vars only for one environment but for all machines (these files are committed);
• .env.<environment>.local (e.g. .env.test.local): defines machine-specific env var overrides only for one environment. It's similar to .env.local, but the overrides only apply to one environment.

Real environment variables always win over env vars created by any of the .env files. Note that this behavior depends on the variables_order configuration, which must contain an E to expose the $_ENV superglobal. This is the default configuration in PHP.

The .env and .env.<environment> files should be committed to the repository 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.

Overriding Environment Variables Defined By The System

If you need to override an environment variable defined by the system, use the overrideExistingVars parameter defined by the loadEnv(), bootEnv(), and populate() methods:

1
2
3
4
5
6

use Symfony\Component\Dotenv\Dotenv;

$dotenv = new Dotenv();
$dotenv->loadEnv(__DIR__.'/.env', overrideExistingVars: true);

// ...

This will override environment variables defined by the system but it won't override environment variables defined in .env files.

Configuring Environment Variables in Production

In production, the .env files are also parsed and loaded on each request. So the easiest way to define env vars is by creating a .env.local file on your production server(s) with your production values.

To improve performance, you can optionally run the dump-env Composer command:

1
2

# parses ALL .env files and dumps their final values to .env.local.php
$ composer dump-env prod

1
2
3

# config/services.yaml
services:
    Symfony\Component\Dotenv\Command\DotenvDumpCommand: ~

1
2

# parses ALL .env files and dumps their final values to .env.local.php
$ APP_ENV=prod APP_DEBUG=0 php bin/console dotenv:dump

After running this command, Symfony will load the .env.local.php file to get the environment variables and will not spend time parsing the .env files.

Storing Environment Variables In Other Files

By default, the environment variables are stored in the .env file located at the root of your project. However, you can store them in other files in multiple ways.

If you use the Runtime component, the dotenv path is part of the options you can set in your composer.json file:

1
2
3
4
5
6
7
8
9

{
    // ...
    "extra": {
        // ...
        "runtime": {
            "dotenv_path": "my/custom/path/to/.env"
        }
    }
}

As an alternate option, you can directly invoke the Dotenv class in your bootstrap.php file or any other file of your application:

1
2
3

use Symfony\Component\Dotenv\Dotenv;

(new Dotenv())->bootEnv(dirname(__DIR__).'my/custom/path/to/.env');

Symfony will then look for the environment variables in that file, but also in the local and environment-specific files (e.g. .*.local and .*.<environment>.local). Read how to override environment variables to learn more about this.

If you need to know the path to the .env file that Symfony is using, you can read the SYMFONY_DOTENV_PATH environment variable in your application.

Encrypting Environment Variables (Secrets)

Instead of defining a real environment variable or adding it to a .env file, if the value of a variable is sensitive (e.g. an API key or a database password), you can encrypt the value using the secrets management system.

Listing Environment Variables

Use the debug:dotenv command to understand how Symfony parses the different .env files to set the value of each environment variable:

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

$ php bin/console debug:dotenv

Dotenv Variables & Files
========================

Scanned Files (in descending priority)
--------------------------------------

* ⨯ .env.local.php
* ⨯ .env.dev.local
* ✓ .env.dev
* ⨯ .env.local
* ✓ .env

Variables
---------

---------- ------- ---------- ------
 Variable   Value   .env.dev   .env
---------- ------- ---------- ------
 FOO        BAR     n/a        BAR
 ALICE      BOB     BOB        bob
---------- ------- ---------- ------

# look for a specific variable passing its full or partial name as an argument
$ php bin/console debug:dotenv foo

Additionally, and regardless of how you set environment variables, you can see all environment variables, with their values, referenced in Symfony's container configuration, you can also see the number of occurrences of each environment variable in the container:

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

$ php bin/console debug:container --env-vars

------------ ----------------- ------------------------------------ -------------
 Name         Default value     Real value                           Usage count
------------ ----------------- ------------------------------------ -------------
 APP_SECRET   n/a               "471a62e2d601a8952deb186e44186cb3"   2
 BAR          n/a               n/a                                  1
 BAZ          n/a               "value"                              0
 FOO          "[1, "2.5", 3]"   n/a                                  1
------------ ----------------- ------------------------------------ -------------

# 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

Creating Your Own Logic To Load Env Vars

You can implement your own logic to load environment variables if the default Symfony behavior doesn't fit your needs. To do so, create a service whose class implements EnvVarLoaderInterface.

Let's say you have a JSON file named env.json containing your environment variables:

1
2
3
4
5
6

{
    "vars": {
        "APP_ENV": "prod",
        "APP_DEBUG": false
    }
}

You can define a class like the following JsonEnvVarLoader to populate the environment variables from the file:

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

namespace App\DependencyInjection;

use Symfony\Component\DependencyInjection\EnvVarLoaderInterface;

final class JsonEnvVarLoader implements EnvVarLoaderInterface
{
    private const ENV_VARS_FILE = 'env.json';

    public function loadEnvVars(): array
    {
        $fileName = __DIR__.\DIRECTORY_SEPARATOR.self::ENV_VARS_FILE;
        if (!is_file($fileName)) {
            // throw an exception or just ignore this loader, depending on your needs
        }

        $content = json_decode(file_get_contents($fileName), true);

        return $content['vars'];
    }
}

That's it! Now the application will look for a env.json file in the current directory to populate environment variables (in addition to the already existing .env files).

1
2
3
4
5

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

# .env.prod (or .env.prod.local) - this will fallback on the loaders you defined
APP_ENV=