Configuring Symfony ¶

Configuration Formats ¶

Unlike other frameworks, Symfony doesn't impose a specific format on you to configure your applications. Symfony lets you choose between YAML, XML and PHP and 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 and caches all of them into PHP before running the application, so there's not even any performance difference between them.

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;
  YAML: シンプルでクリーンで読みやすいですが、すべての IDE が自動補完と検証をサポートしているわけではありません。 YAML 構文を学びます。
• XML: autocompleted/validated by most IDEs and is parsed natively by PHP, but sometimes it generates configuration considered too verbose. Learn the XML syntax;
  XML: ほとんどの IDE でオートコンプリート/検証され、PHP によってネイティブに解析されますが、冗長すぎると見なされる構成が生成されることがあります。 XML 構文を学びます。
• PHP: very powerful and it allows you to create dynamic configuration with arrays or a ConfigBuilder.
  PHP: 非常に強力で、配列または 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) {
    $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/);
   環境と同じ名前 (この場合は 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;
   config/packages/staging/ に必要な構成ファイルを追加して、新しい環境の動作を定義します。 symfony は config/packages/*.yaml ファイルを最初にロードするので、それらのファイルとの違いを設定するだけで済みます。
3. Select the staging environment using the APP_ENV env var as explained in the previous section.
   前のセクションで説明したように、APP_ENV 環境変数を使用してステージング環境を選択します。

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: アプリケーションが必要とする環境変数のデフォルト値を定義します。
• .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.local: すべての環境のデフォルト値をオーバーライドしますが、ファイルが含まれるマシンでのみオーバーライドします。このファイルはリポジトリにコミットするべきではなく、テスト環境では無視されます (テストは全員に対して同じ結果を生成する必要があるため)。
• .env.<environment> (e.g. .env.test): overrides env vars only for one environment but for all machines (these files are committed);
  .env。 (例: .env.test): 1 つの環境に対してのみ、すべてのマシンに対して環境変数をオーバーライドします (これらのファイルはコミットされます)。
• .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.
  .env..local (例: .env.test.local): 1 つの環境に対してのみ、マシン固有の環境変数オーバーライドを定義します。 .env.local に似ていますが、オーバーライドは 1 つの環境にのみ適用されます。

Real environment variables always win over env vars created by any of the .env files.

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.

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 command (available in Symfony Flex 1.2 or later):

1
2

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

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.

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:

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

$ 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