Конфігурація Symfony

Дата оновлення перекладу 2024-06-07

Конфігурація Symfony

Файли конфігурації

Додатки Symfony сконфігуровані з файлами, що зберігаються в каталозі config/, який за замовчуванням має наступну структуру:

        1
2
3
4
5
6
        your-project/
├─ config/
│  ├─ packages/
│  ├─ bundles.php
│  ├─ routes.yaml
│  └─ services.yaml
    

Файл routes.yaml визначає конфігурацію маршрутизації;
Файл services.yaml конфігурує сервіси сервіс-контейнеру;
Файл bundles.php вмикає/вимикає пакети у вашому додатку.
Каталог config/packages/ зберігає конфігурацію кожного пакета, встановленого у вашому додатку.

Пакети (які також називаються "bundles" в Symfony і "plugins/modules" в інших проектах) додають готові до використання функції до ваших проектів.

При використанні Symfony Flex , який в додаткаї Symfony ввімкнено за замовчуванням, пакети оновлюють файл bundles.php та створюють нові файли в config/packages/ автоматично під час установки. Наприклад, це файл за замовчуванням, який створено пакетом "API Platform":

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

Розділення конфігурації на безліч маленьких файлів лякає деяких новачків в Symfony. Однак ви швидко до них звикнете і вам рідко коли необхідно буде змінювати ці файли після установки пакету.

Tip

Щоб дізнатися все про доступні опції конфігурації, подивіться довідник конфігурації Symfony або виконайте команду config:dump-reference.

Формати конфігурації

На відміну від інших фреймворків, Symfony не змушує вас використовувати конкретний формат для конфігурації додатку. Symfony дозволяє вам обирати між YAML, XML та PHP, і по всій документації Symfony, всі приклади конфігурації будуть продемонстровані в цих трьох форматах.

Між форматами немає практичної різниці. Насправді, Symfony трансформує та кешує їх всі в PHP перед запуском додатку, так що між ними навіть немає різниці у продуктивності.

YAML використовується за замовчуванням при установці пакетів так як він лаконічний та дуже читаний. Ось основні переваги та недоліки кожного формату:

YAML: простий, чистий та читаний, але не всі IDE підтримують автозаповнення та валідацію для нього. Дізнайтеся про синтаксіс YAML ;
XML: автозаповнюється/валідується більшістю IDE та нативно аналізується PHP, але інколи генерує конфігурацію, яка вважається надто перевантаженою. Вивчіть синтаксис XML;
PHP: дуже потужний та дозволяє вам створювати динамічну конфігурацію з масивами або ConfigBuilder .

Note

За замовчуванням, Symfony завантажує файли конфігурації, визначені у форматах YAML та PHP. Якщо ви визначаєте конфігурацію у форматі XML, оновіть файл src/Kernel.php, щоб додати підтримку для розширення файлу .xml.

Імпорт файлів конфігурації

Symfony завантажує файли конфігурації з використанням компонента Config, який надає просунуті функції, такі як імпорт інших файлів конфігурації, навіть якщо вони використовують інший формат:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        # config/services.yaml
imports:
    - { resource: 'legacy_config.php' }

    # глобальні вирази також підтримують завантаження декількох файлів
    - { resource: '/etc/myapp/*.yaml' }

    # ignore_errors: not_found тихо видаляє помилки у випадку, якщо завантажений файл не існує
    - { resource: 'my_config_file.xml', ignore_errors: not_found }
    # ignore_errors: true тихо видаляє всі помилки (включно з невірним кодом та не знайдено)
    - { 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"/>
        <!-- глобальні вирази також підтримують завантаження декількох файлів -->
        <import resource="/etc/myapp/*.yaml"/>

        <!-- ignore-errors="not_found" тихо видаляє помилки у випадку, якщо завантажений файл не існує -->
        <import resource="my_config_file.yaml" ignore-errors="not_found"/>
        <!-- ignore-errors="true" тихо видаляє всі помилки (включно з невірним кодом та не знайдено) -->
        <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');

    // глобальні вирази також підтримують завантаження декількох файлів
    $container->import('/etc/myapp/*.yaml');

    // третій необов'язковий аргумент import() - 'ignore_errors'
    // 'ignore_errors' встановлений як 'not_found' тихо видаляє помилки у випадку, якщо завантажений файл не існує
    $container->import('my_config_file.yaml', null, 'not_found');
    // 'ignore_errors' тихо видаляє всі помилки (включно з невірним кодом та не знайдено)
    $container->import('my_config_file.yaml', null, true);
};

// ...
    

Параметри конфігурації

Інколи одне і те саме значення конфігурації використовується в декількох файлах конфігурації. Замість його повторення, ви можете визначити його як "параметр", що є чимось на кшталт повторно використовуваного значення конфігурації. За згодою, параметри визначаються під ключем parameters в файлі config/services.yaml:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        # config/services.yaml
parameters:
    # ім'я параметру - довільний рядок (рекомендовано префікс 'app.'
    # для кращої диференціації ваших параметрів від параметрів Symfony).
    app.admin_email: 'something@example.com'

    # булеві параметри
    app.enable_v2_protocol: true

    # параметри масиву/колекції
    app.supported_locales: ['en', 'es', 'fr']

    # параметри бінарного змісту (закодуйте його з допомогою base64_encode())
    app.some_parameter: !!binary VGhpcyBpcyBhIEJlbGwgY2hhciAH

    # PHP-константи в якості значень параметру
    app.some_constant: !php/const GLOBAL_CONSTANT
    app.another_constant: !php/const App\Entity\BlogPost::MAX_ITEMS

# ...
    

        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
30
31
32
33
34
35
36
37
        <!-- 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>
        <!-- ім'я параметру - довільний рядок (рекомендовано префікс 'app.'
             для кращої диференціації ваших параметрів від параметрів Symfony). -->
        <parameter key="app.admin_email">something@example.com</parameter>

        <!-- булеві параметри -->
        <parameter key="app.enable_v2_protocol">true</parameter>
        <!-- якщо ви віддаєте перевагу зберіганню булевого значення в якості рядку в параметрі -->
        <parameter key="app.enable_v2_protocol" type="string">true</parameter>

        <!-- параметри масиву/колекції -->
        <parameter key="app.supported_locales" type="collection">
            <parameter>en</parameter>
            <parameter>es</parameter>
            <parameter>fr</parameter>
        </parameter>

        <!-- параметри бінарного змісту (закодуйте його з допомогою base64_encode()) -->
        <parameter key="app.some_parameter" type="binary">VGhpcyBpcyBhIEJlbGwgY2hhciAH</parameter>

        <!-- PHP-константи в якості значень параметру -->
        <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>
    

        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
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Entity\BlogPost;

return static function (ContainerConfigurator $container): void {
    $container->parameters()
        // ім'я параметру - довільний рядок (рекомендовано префікс 'app.'
        // для кращої диференціації ваших параметрів від параметрів Symfony).
        ->set('app.admin_email', 'something@example.com')

        // булеві параметри
        ->set('app.enable_v2_protocol', true)

        // параметри масиву/колекції
        ->set('app.supported_locales', ['en', 'es', 'fr'])

        // параметри бінарного змісту (використовуйте керуючі послідовності PHP)
        ->set('app.some_parameter', 'This is a Bell char: \x07')

        // PHP-константи в якості значень параметру
        ->set('app.some_constant', GLOBAL_CONSTANT)
        ->set('app.another_constant', BlogPost::MAX_ITEMS);
};

// ...
    

Caution

При використанні XML-конфігурації, значення між тегами <parameter> не обрізаються. Це означає, що значення наступного параметру буде '\n something@example.com\n':

        1
2
3
        <parameter key="app.admin_email">
    something@example.com
</parameter>
    

Коли він буде визначений, ви можете послатися на значення цього параметру з будь-якого іншого файлу конфігурації, використовуючи спеціальний синтаксис: оберніть ім'я параметру в два % (наприклад, %app.admin_email%):

        1
2
3
4
5
6
        # config/packages/some_package.yaml
some_package:
    # будь-який рядок, оточений двома %, замінюється цим значенням параметру
    email_address: '%app.admin_email%'

    # ...
    

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

    <!-- будь-який рядок, оточений двома %, замінюється цим значенням параметру -->
    <some-package:config email-address="%app.admin_email%">
        <!-- ... -->
    </some-package:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/packages/some_package.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return static function (ContainerConfigurator $container): void {
    $container->extension('some_package', [
        // будь-який рядок, оточений двома %, замінюється цим значенням параметру
        'email_address' => '%app.admin_email%',

        // ...
    ]);
};
    

Note

Якщо якесь значення параметру включає в себе символ %, вам необхідно екранувати його, додавши ще один %, щоб Symfony не сприйняла його в якості посилання на ім'я параметру:

        1
2
3
4
        # config/services.yaml
parameters:
    # Аналізується як 'https://symfony.com/?foo=%s&amp;bar=%d'
    url_pattern: 'https://symfony.com/?foo=%%s&amp;bar=%%d'
    

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

        1
2
3
4
5
6
7
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return static function (ContainerConfigurator $container): void {
    $container->parameters()
        ->set('url_pattern', 'http://symfony.com/?foo=%%s&amp;bar=%%d');
};
    

Дата оновлення перекладу 2023-08-21

Note

У звʼязку з тим, як розвʼязуються параметри, ви не можете використовувати їх для побудови шляхів в імпорті динамічно. Це означає, що щось на кшталт цього працювати не буде:

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

        1
2
3
4
5
6
7
8
9
10
11
        <!-- 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>
    

        1
2
3
4
5
6
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return static function (ContainerConfigurator $container): void {
    $container->import('%kernel.project_dir%/somefile.yaml');
};
    

Параметри конфігурації дуже розповсюджені в додатках Symfony. Деякі пакети навіть визначають свої власні параметри (наприклад, при встановленні пакету перекладів, в файл config/services.yaml додається новий параметр locale).

Tip

За угодою, параметри, імена яких починаються з крапки . (наприклад, .mailer.transport), доступні лише під час компіляції контейнера. Вони корисні при роботі з Передачами Компілятора для оголошення деяких тимчасових параметрів, які не будуть доступні пізніше у додатку.

See also

Пізніше в цій статті ви можете прочитати як отримувати параметри конфігурації в контролерах та сервісах .

Середовища конфігурації

У вас є лише один застосунок, але розумієте ви це, чи ні, вам необхідно, щоб він поводив себе по-різному за різних обставин:

Під час розробки, вам необхідно вести логи усього і мати гарні інструменти налагодження;
Після запуску у виробництво, вам необхідно, щоб той же застосунок було оптимізовано для швидкості і вело логи тільки для помилок.

Файли, що зберігаються в config/packages/, використовуються Symfony для конфігурації сервісів додатку. Іншими словами, ви можете змінити поведінку додатку, змінивши те, які файли конфігурації завантажуються. В цьому полягає ідея середовищ конфігурації Symfony.

Типовий застосунок Symfony починається з трьох середовищ:

dev для локальної розробки,
prod для виробничих серверів,
test для автоматизованих тестів. П

При запуску додатку, Symfony завантажує файли конфігурації в цьому порядку (останні файли можуть перевизначити значення, які були встановлені в попередніх):

Файли в config/packages/*.<extension>;
Файли в config/packages/<environment-name>/*.<extension>;
config/services.<extension>;
config/services_<environment-name>.<extension>.

Візьмемо пакет framework, встановлений за замовчуванням, в якості прикладу:

Спочатку завантажується config/packages/framework.yaml у всіх середовищах та конфігурує фреймворк з деякими опціями;
В середовищі prod не буде встановлено нічого додатково, так як відсутній файл config/packages/prod/framework.yaml;
В середовищі dev, також відсутній файл (config/packages/dev/framework.yaml не існує).
В середовищі test, файл config/packages/test/framework.yaml завантажується для перевизначення деяких з налаштувань, що були раніше сконфігуровані в config/packages/framework.yaml.

В реальності, кожне середовище відрізняється від інших лише трошки. Це означає, що всі середовища мають спільну базу конфігурації, яка розташовує файли напряму в каталозі config/packages/.

Tip

Ви також можете визначити опції для різних середовищ в одному файлі конфігурації, використовуючи спеціальне ключове слово when:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        # config/packages/webpack_encore.yaml
webpack_encore:
    # ...
    output_path: '%kernel.project_dir%/public/build'
    strict_mode: true
    cache: false

# кеш включено лише у середовищі "prod"
when@prod:
    webpack_encore:
        cache: true

# відключити суворий режим лише у середовищі "test"
when@test:
    webpack_encore:
        strict_mode: false

# синтаксис YAML дозволяє повторно використовувати зміст, використовуючи "якорі" (&some_name) та "псевдоніми" (*some_name).
# У цьому прикладі, конфігурація 'test' використовує точно таку ж конфігурацію, як і в 'prod'
when@prod: &webpack_prod
    webpack_encore:
        # ...
when@test: *webpack_prod
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
        <!-- config/packages/webpack_encore.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">
    <webpack-encore:config
        output-path="%kernel.project_dir%/public/build"
        strict-mode="true"
        cache="false"
    />

    <!-- кеш включено лише у середовищі "prod" -->
    <when env="prod">
        <webpack-encore:config cache="true"/>
    </when>

    <!-- відключити суворий режим лише у середовищі "test" -->
    <when env="test">
        <webpack-encore:config strict-mode="false"/>
    </when>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        // config/packages/framework.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symfony\Config\WebpackEncoreConfig;

return static function (WebpackEncoreConfig $webpackEncore, ContainerConfigurator $container): void {
    $webpackEncore
        ->outputPath('%kernel.project_dir%/public/build')
        ->strictMode(true)
        ->cache(false)
    ;

    // кеш включено лише у середовищі "prod"
    if ('prod' === $container->env()) {
        $webpackEncore->cache(true);
    }

    // відключити суворий режим лише у середовищі "test"
    if ('test' === $container->env()) {
        $webpackEncore->strictMode(false);
    }
};
    

See also

Див. також метод configureContainer() класу Kernel, щоб дізнатися все про порядок завантаження файлів конфігурації.

Вибір активного середовища

Додатки Symfony мають файл під назвою .env, який знаходиться в кореневому каталозі проекту. Цей файл використовується для визначення значення змінних середовища, та детально пояснюється далі в цій статті.

Відкрийте файл .env (а краще файл .env.local, якщо ви його створювали), та відредагуйте значення змінної APP_ENV, щоб змінити середовище, в якому працює застосунок. Наприклад, запустіть застосунок у виробництві:

        1
2
        # .env (або .env.local)
APP_ENV=prod
    

Це значення використовується як для веб-команд, так і для консольних. Однак, ви можете перевизначити його для команд, встановивши значення APP_ENV до їх запуску:

        1
2
3
4
5
        # Використовуйте середовище, визначене в файлі .env
$ php bin/console command_name

# Ігноруйте файл .env та виконайте цю команду у виробництві
$ APP_ENV=prod php bin/console command_name
    

Створення нового середовища

Трьох середовищ наданих Symfony за замовчуванням достатньо для більшості проектів, але ви також можете визначати власні середовища. Наприклад, ось як ви можете визначити середовище staging, де клієнт може тестувати проект до його запуску у виробництво:

Створіть каталог конфігурації з тим же іменем, що і у середовища (в даному випадку, config/packages/staging/);
Додайте необхідні файли конфігурації в config/packages/staging/, щоб визначити поведінку нового середовища. Symfony завантажує файли config/packages/*.yaml першими, тому вам необхідно сконфігурувати лише різницю в цих файлах;
Оберіть середовище staging, використовуючи варіант середовища APP_ENV, як пояснювалося у попередньому розділі.

Tip

Середовища часто схожі одне на одне, тому ви можете використовувати символьні посилання між каталогами config/packages/<environment-name>/, щоб повторно використовувати одну й ту саму конфігурацію.

Замість створення нових середовищ, ви можете використовувати змінні середовища, як пояснюється у наступному розділі. Таким чином ви можете використовувати однакові додаток та середовище (наприклад, prod), але змінити його поведінку завдяки конфігурації, заснованій на зміннних середовища (наприклад, щоб запустити додаток в інших сценаріях: постановці, контролю якості, рецензуванні клієнтом тощо).

Конфігурація, заснована на змінних середовища

Використання змінних середовища (або скорочено "env vars") - це розповсюджена практика для конфігурації опцій, які залежать від того, де запускається застосунок (наприклад, ідентифікаційні дані бази даних зазвичай відрізняються у виробництві та на вашій локальній машині). Якщо значення чутливі, ви навіть можете закодувати їх як секретні.

Ви можете послатися на змінні середовища, використовуючи спеціальний синтаксіс %env(ENV_VAR_NAME)%. Значення цих опцій дозволяється під час виконання (лише один раз за запит, щоб не вплинути на этих опций разрешаются во время выполнения (только единожды за запрос, чтобы не повлиять на продуктивність).

Цей приклад демонструж, як ви можете сконфігурувати з'єднання бази даних, використовуючи змінну середовища:

        1
2
3
4
5
6
        # config/packages/doctrine.yaml
doctrine:
    dbal:
        # за згодою, імена змінних середовищ завжди використовують верхній регістр
        url: '%env(resolve:DATABASE_URL)%'
    # ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        <!-- 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>
        <!-- за згодою, імена змінних середовищ завжди використовують верхній регістр -->
        <doctrine:dbal url="%env(resolve:DATABASE_URL)%"/>
    </doctrine:config>

</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/packages/doctrine.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return static function (ContainerConfigurator $container): void {
    $container->extension('doctrine', [
        'dbal' => [
            // за згодою, імена змінних середовищ завжди використовують верхній регістр
            'url' => '%env(resolve:DATABASE_URL)%',
        ]
    ]);
};
    

Note

Ваші змінні середовища також можуть бути доступні через супер-глобальні PHP $_ENV та $_SERVER (обидва рівнозначні):

        1
2
        $databaseUrl = $_ENV['DATABASE_URL']; // mysql://db_user:db_password@127.0.0.1:3306/db_name
$env = $_SERVER['APP_ENV']; // prod
    

Однак, у додатках Symfony немає потреби в їх використанні, так як система конфігурації надає кращий спосіб роботи зі змінними середовища.

See also

Значення змінних середовища можуть бути лише рядками, але Symfony має деякі процесори env var, щоб трансформувати їхній зміст (наприклад, перетворити значення рядку в ціле число).

Щоб визначити значення будь-якої змінної середовища, у вас є декілька варіантів:

Додати значення до файлу .env ;
Закодувати значення як секрет ;
Встановити значення як реальну змінну середовища в вашій оболонці бо веб-сервері.

Якщо ваш додаток намагається використати змінну середовища, яку не було визначено, ви побачите виключення. Ви можете запобігти цьому, визначивши значення за замовчуванням для змінної середовища. Для цього визначте параметр з такою самою назвою, як і змінна середовища, використовуючи цей синтаксис:

        1
2
3
4
5
6
        # config/packages/framework.yaml
parameters:
    # якщо значення SECRET змінної середовища ніде не визначено, Symfony використовує це значення
    env(SECRET): 'some_secret'

# ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- config/packages/framework.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>
        <!--  якщо значення SECRET змінної середовища ніде не визначено, Symfony використовує це значення -->
        <parameter key="env(SECRET)">some_secret</parameter>
    </parameters>

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

        1
2
3
4
5
6
7
8
9
10
11
12
        // config/packages/framework.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Config\FrameworkConfig;

return static function (ContainerBuilder $container, FrameworkConfig $framework) {
    // якщо значення SECRET змінної середовища ніде не визначено, Symfony використовує це значення
    $container->setParameter('env(SECRET)', 'some_secret');

    // ...
};
    

Tip

Деякі хостінги - як SymfonyCloud - пропонують прості у виробництві утіліти для роботи з env var

Note

Деякі функції конфігурації несумісні зі змінними середовища. Наприклад, визначення деяких параметрів контейнера залежно від умов, засновуючись на існуванні іншої опції конфігурації. При використанні змінної середоовища, опція конфігурації завжди існує, так як її значення буде null, якщо повʼязана змінна середовища не визначена.

Danger

Майте на увазі, що скидання змісту змінних $_SERVER та $_ENV або виведення змісту phpinfo() відобразить значення змінних середовища, оголюючи чутливу інформацію на кшталт ідентифікаційних даних бази даних.

Значення змінних середовища також розкриваються у веб-інтерфейсі профілювальника Symfony. На практиці це не має бути проблемою, так як веб-профільувальник ніколи не має бути увімкнений у виробництві.

Конфігурація змінних середовища у файлах .env

Замість визначення змінних середовища у вашій оболонці або веб-сервері, Symfony надає зручний спосіб визначити їх в файлі .env (починається з крапки), що знаходиться в корені вашого проекту.

Файл .env читається та аналізується при кожному запиті і його змінні середовища додаються до PHP-змінних $_ENV та $_SERVER. Всі існуючі змінні середовища ніколи не перевизначаються значеннями, визначеними в .env, тому ви можете їх комбінувати.

Наприклад, щоб визначити змінні середовища DATABASE_URL, продемонстровані раніше в цій статті, ви можете додати:

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

Цей файл має бути надісланий у ваше сховище, і (у зв'язку з цим фактом) має містити лище значення "за замовчуванням", які підохдять для локальної розробки. Цей файл не має містити значень виробництва.

На додаток до ваших власних змінних середовища, цей файл .env також містить змінні середовища, визначені сторонніми пакетами, що встановлені в вашому додатку (вони автоматично додаються Symfony Flex при установці пакетів).

Tip

Так як файл .env читається та парсується за кожним запитом, вам не потрібно очищувати кеш Symfony або перезавантажувати PHP контейнер, якщо ви використовуєте Docker.

Синтаксис файлу .env

Додавайте коментарі з префіксом #:

        1
2
3
        # повноваження бази даних
DB_USER=root
DB_PASS=pass # це секретний пароль
    

Використовуйте змінні середовища в значеннях, додаючи до них префікс $:

        1
2
        DB_USER=root
DB_PASS=${DB_USER}pass # додайте користувача в якості префіксу пароля
    

Caution

Порядок важливий, коли деякі зі змінних середовища залежать від значення інших змінних середовища. У прикладі вище, DB_PASS повиен бути визначений після DB_USER. Більш того, якщо ви визначаєте декілька файлів .env та ставите DB_PASS першим, його значення залежатиме від значення DB_USER, визначеного в інших файлах, замість значення, визначеного у цьому файлі.

Визначте значення за замовчуванням у випадку, якщо змінна середовища не встановлена:

        1
2
        DB_USER=
DB_PASS=${DB_USER:-root}pass # результати в DB_PASS=rootpass
    

Вбудуйте команди через $() (не підтримується у Windows):

        1
        START_TIME=$(date)
    

Caution

Використання $() може не працювати в залежності від вашої оболонки.

Tip

Так як файл .env - звичайний скрипт оболонки, ви можете source його у ваших власних скриптах оболонки:

        1
        $ source .env
    

Перевизначення значень середовища через .env.local

Якщо вам потрібно перевизначити значення середовища (наприклад, на інше значення на вашій локальній машині), ви можете зробити це в файлі .env.local:

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

Цей файл має бути проігнорований git і не має бути відправлений до вашого сховища. Декілька інших файлів .env доступні для установки змінних середовища лише у правильних ситуаціях:

.env: визначає значення за замовчуванням для змінних середовища, які необхідні додатку;
.env.local: перевизначає значення за замовчуванням для всіх середовищ, але лише на машині, що містить цей файл. Цей файл не має бути відправлений у сховище, він ігнорується в середовищі test (так як тести мають виробляти однакові результати для всіх);
.env.<environment> (наприклад, .env.test): перевизначає змінні середовища лише для одного середовища, але для всіх машин (ці файли відправляються);
.env.<environment>.local (наприклад, .env.test.local): визначає змінні середовища, які відносяться до конкретної машини, перевизначаючи їх лише для одного середовища. Схоже на .env.local, але перевизначення застосовується лише до одного середовища.

Справжні змінні середовища завжди мають перевагу над змінними середовища, створеними будь-яким з файлів .env. Зауважте, що ця поведінка залежить від конфігурації variables_order, яка має містити E, щоб показати суперглобальну змінну $_ENV. Це конфігурація за замовчуванням у PHP.

Файли .env та .env.<environment> не повинні бути відправлені в сховище, так як вони однакові для всіх розробників та машин. Однак, файли env, які закінчуються на .local (.env.local та .env.<environment>.local) не мають бути відправлені, так як їх будете використовувати лише ви. Насправді, файл .gitignore, який постачається з Symfony, запобігає їхньому відправленню.

Перевизначення змінних середовища, визначених системою

Якщо вам потрібно перевизначити змінну середовища, визначену системою, використовуйте параметр overrideExistingVars, визначений методами loadEnv(), bootEnv() та
populate():

        1
2
3
4
5
6
        use Symfony\Component\Dotenv\Dotenv;

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

// ...
    

Це призведе до перевизначення змінних середовища, визначених системою, але не перевизначить змінні середовища, визначені у файлах .env.

Конфігурація змінних середовища у виробництві

У виробництві, файли .env також аналізуються та завантажуються по кожному запиту. Тому найпростіший спосіб визначити змінні середовища - розгорнути файл .env.local на вашому виробничому сервері(ах) з вашими значеннями виробництва.

Для покращення продуктивності, ви можете за бажанням виконати команду Composer dump-env:

        1
2
        # аналізує ВСІ файли .env та скидає їх фінальні значення в .env.local.php
$ composer dump-env prod
    

Якщо у вас у виробництві не встановлено Composer, ви можете скористатися командою dotenv:dump (доступна у Symfony Flex 1.2 або новішої версії). Команда не зареєстрована за замовчуванням, тому ви спочатку повинні зареєструвати її у вашому сервісі:

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

Потім виконайте команду:

        1
2
        # аналізує ВСІ файли .env та скидає їхні фінальні значення у .env.local.php
$ APP_ENV=prod APP_DEBUG=0 php bin/console dotenv:dump
    

Після виконання цієї команди, Symfony завантажить файл .env.local.php, щоб отримати змінні середовища, і не буде витрачати час, аналізуючи файли .env.

Tip

Оновіть ваші інструменти/робочий процес, щоб запускати команду dotenv:dump після кожного розгортання для покращення продуктивності програми.

Зберігання змінних середовища в інших файлах

За замовчуванням, змінні середовища зберігаються у файлі .env, розташованому в корені вашого проекту. Однак, ви можете зберігати їх в інших файлах у різними способами.

Якщо ви використовуєте компонент Runtime, шлях dotenv шлях є частиною опцій, які ви можете задати у вашому файлі composer.json:

        1
2
3
4
5
6
7
8
9
        {
    // ...
    "extra": {
        // ...
        "runtime": {
            "dotenv_path": "my/custom/path/to/.env"
        }
    }
}
    

Ви також можете встановити змінну середовища SYMFONY_DOTENV_PATH на системному рівні (наприклад, у конфігурації вашого веб-сервера або у вашому Docker-файлі):

        1
2
        # .env (або .env.local)
SYMFONY_DOTENV_PATH=my/custom/path/to/.env
    

Нарешті, ви можете напряму викликати клас Dotenv у вашому bootstrap.php або будь-якому іншому файлі вашого додатку:

        1
2
3
        use Symfony\Component\Dotenv\Dotenv;

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

Після цього Symfony шукатиме змінні середовища у цьому файлі, а також у локальних та специфічних для середовища файлах (наприклад, .*.local та .*.<environment>.local). Прочитайте як перевизначити змінні середовища , щоб дізнатися більше про це.

7.1

Змінна середовища SYMFONY_DOTENV_PATH була представлена в Symfony 7.1.

Кодування змінних середовища (секрети)

Замість визначення реальної змінної середовища, або її додавання в файл .env, якщо значення змінної чутливе (наприклад, ключ API або пароль БД), ви можете закодувати значення, використовуючи систему управління секретами.

Перелік змінних середовища

Використовуйте команду debug:dotenv, щоб розуміти, як Symfony аналізує різні файли .env, щоб встановити значення кожної змінної середовища:

        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 змінні та файли
======================

Проскановані файли (в порядку зниження пріорітету)
--------------------------------------------------

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

Змінні
------

------------ ---------- ---------- ------
 Змінна      Значення   .env.dev   .env
------------ ---------- ---------- ------
 FOO          BAR        n/a        BAR
 ALICE        BOB        BOB        bob
------------ ---------- ---------- ------

# шукати конкретну змінну, що передає своє повне або часткове імʼя в якості аргументу
$ php bin/console debug:dotenv foo
    

Крім того, незалежно від того, як ви встановили змінні середовища, ви можете бачити всі змінні середовища з їх значеннями, на які є посилання у конфігурації контейнера Symfony, ви також можете побачити кількість випадків використання кожної змінної середовища у контейнері:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        $ php bin/console debug:container --env-vars

------------ --------------------------- ------------------------------------ -----------------------
 Імʼя         Значення за замовчуванням   Справжнє значення                    Кількість використань
------------ --------------------------- ------------------------------------ -----------------------
 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
------------ --------------------------- ------------------------------------ -----------------------

# ви також можете відфільтрувати список env vars за іменем:
$ php bin/console debug:container --env-vars foo

# виконайте цю команду, щоб показати всі деталі для конкретної  env var:
$ php bin/console debug:container --env-var=FOO
    

Створення вашої власної логіки для завантаження змінних середовища

Ви можете реалізувати власну логіку завантаження змінних середовища, якщо поведінка Symfony за замовчуванням не відповідає вашим потребам. Для цього створіть сервіс, клас якого реалізує EnvVarLoaderInterface.

Note

Якщо ви використовуєте конфігурацію services.yaml за замовчуванням , функція автоконфігурації увімкне і тегує цей сервіс автоматично. В іншому випадку, вам потрібно зареєструвати і тегувати ваш сервіс тегом container.env_var_loader.

Припустимо що у вас є JSON-файл з ім'ям env.json, який містить ваші змінні середовища:

        1
2
3
4
5
6
        {
    "vars": {
        "APP_ENV": "prod",
        "APP_DEBUG": false
    }
}
    

Ви можете визначити клас на зразок наступного JsonEnvVarLoader для заповнення змінних середовища з файлу:

        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)) {
            // викликати виключення або просто проігнорувати цей завантажувач, залежно від ваших потреб
        }

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

        return $content['vars'];
    }
}
    

Ось і все! Тепер додаток буде шукати файл env.json у поточному каталозі для заповнення змінних середовища (на додачу до вже існуючих файлів .env).

Tip

Якщо ви хочете, щоб змінна середовища мала значення у певному середовищі, але користуватися резервом завантажувачів в іншому середовищі, призначте порожнє значення змінній середовища для середовища, у якому ви хочете використовувати завантажувачі:

        1
2
3
4
5
        # .env (або .env.local)
APP_ENV=prod

# .env.prod (або .env.prod.local) - це використовуватиме резерв тих завантажувачів, які ви визначили
APP_ENV=
    

Доступ до параметрів конфігурації

Контролери та сервіси можуть отримати доступ до всіх параметрів конфігуацрії. Це включає в себе як параметри, визначені вами , так і параметри, створені пакетами. Виконайте наступну команду, щоб побачити всі параметри, які існують у вашому додатку:

        1
        $ php bin/console debug:container --parameters
    

У контролерах, що розширюються з AbstractController , використовуйте хелпер getParameter():

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // src/Controller/UserController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;

class UserController extends AbstractController
{
    // ...

    public function index(): Response
    {
        $projectDir = $this->getParameter('kernel.project_dir');
        $adminEmail = $this->getParameter('app.admin_email');

        // ...
    }
}
    

У сервісах та контролерах, які не розширюються з AbstractController, впровадьте параметри в якості аргументів їх конструкторів. Ви маєте впровадити їх чітко, тому що автоматичне впровадження сервісів не працює для параметрів:

        1
2
3
4
5
6
7
8
        # config/services.yaml
parameters:
    app.contents_dir: '...'

services:
    App\Service\MessageGenerator:
        arguments:
            $contentsDir: '%app.contents_dir%'
    

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

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Service\MessageGenerator;

return static function (ContainerConfigurator $container): void {
    $container->parameters()
        ->set('app.contents_dir', '...');

    $container->services()
        ->get(MessageGenerator::class)
            ->arg('$contentsDir', '%app.contents_dir%');
};
    

Якщо ви будете вроваджувати одні й ті самі параметри знов і знов, використовуйте замість цього опцію services._defaults.bind. Аргументи, визначені в цій опції, впроваджуються автоматично кожного разу, коли конструктор сервісу або дія контролера визначає аргумент з точно таким же іменем. Наприклад, щоб впроваджувати значення параметра kernel.project_dir , кожний раз, коли сервіс/контролер визначає аргумень $projectDir, використовуйте це:

        1
2
3
4
5
6
7
8
9
        # config/services.yaml
services:
    _defaults:
        bind:
            # передайте це значення будь-якому аргументу $projectDir для будь-якого сервісу,
            # створеного в цьому файлі (включно з аргументами контролера)
            $projectDir: '%kernel.project_dir%'

    # ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- 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">
            <!-- передайте це значення будь-якому аргументу $projectDir для будь-якого сервісу,
                 створеного в цьому файлі (включно з аргументами контролера) -->
            <bind key="$projectDir">%kernel.project_dir%</bind>
        </defaults>

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

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Controller\LuckyController;

return static function (ContainerConfigurator $container): void {
    $container->services()
        ->defaults()
            // передайте це значення будь-якому аргументу $projectDir для будь-якого сервісу,
            // створеного в цьому файлі (включно з аргументами контролера)
            ->bind('$projectDir', '%kernel.project_dir%');

    // ...
};
    

See also

Прочитайте статтю про об'єднання аргументів за іменем та/або типом , щоб дізнатися більше про цю потужну функцію.

Нарешті, якщо якомусь сервісу необхідний доступ до багатьох параметрів, замість впровадження кожного з них окремо, ви можете впровадити всі параметри додатку одночасно, додавши підказки при введені коду до будь-якого з аргументів конструктора з ContainerBagInterface:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        // src/Service/MessageGenerator.php
namespace App\Service;

// ...

use Symfony\Component\DependencyInjection\ParameterBag\ContainerBagInterface;

class MessageGenerator
{
    public function __construct(
        private ContainerBagInterface $params,
    ) {
    }

    public function someMethod(): void
    {
        // отримайте будь-який параметр контейнеру з $this->params, який зберігає їх всі
        $sender = $this->params->get('mailer_sender');
        // ...
    }
}
    

Використання PHP ConfigBuilders

Написання PHP-конфігурації інколи буває складним, тому що у вас виходять великі вкладені масиви, і у вас немає допомоги а автозаповнюванні з вашого улюбленого IDE. Це можна вирішити з допомогою "ConfigBuilders". Це об'єкти, які допоможуть вам будувати ці масиви.

Symfony генерує класи ConfigBuilder автоматично в каталозі будови ядра для всіх пакетів, встановлених у вашому додатку. За згодою, вони всі живуть в просторі імен Symfony\Config:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security): void {
    $security->firewall('main')
        ->pattern('^/*')
        ->lazy(true)
        ->security(false);

    $security
        ->roleHierarchy('ROLE_ADMIN', ['ROLE_USER'])
        ->roleHierarchy('ROLE_SUPER_ADMIN', ['ROLE_ADMIN', 'ROLE_ALLOWED_TO_SWITCH'])
        ->accessControl()
            ->path('^/user')
            ->roles('ROLE_USER');

    $security->accessControl(['path' => '^/admin', 'roles' => 'ROLE_ADMIN']);
};
    

Note

Тільки кореневі класи в просторі імен Symfony\Config є ConfigBuilders. Вкладені конфігурації (наприклад, \Symfony\Config\Framework\CacheConfig) є звичайними PHP об'єктами, які не впроваджуються автоматично під час їх використання в якості типу аргументу.

Note

Для того, щоб отримати автозаповнення ConfigBuilders у вашому IDE/редакторі, переконайтеся, що ви не виключили каталог, в якому генеруються ці класи (за замовчуванням, var/cache/dev/Symfony/Config/).

Не зупиняйтесь!

Вітаємо! Ви впоралися з основами Symfony. Далі, дізнайтеся про кожну частину Symfony окремо, слідуючи посібникам. Подивіться:

І всі інші теми, пов'язані з конфігурацією: