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

Дата оновлення перекладу 2022-12-12

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

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

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

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

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

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

При використанні 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.

6.1

Автоматичне завантаження файлів конфігурації PHP було представлено в Symfony 6.1.

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

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

YAML
XML
PHP

        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) {
    $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:

YAML
XML
PHP

        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) {
    $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%):

YAML
XML
PHP

        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) {
    $container->extension('some_package', [
        // будь-який рядок, оточений двома %, замінюється цим значенням параметру
        'email_address' => '%app.admin_email%',

        // ...
    ]);
};
    

Note

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

YAML
XML
PHP

        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) {
    $container->parameters()
        ->set('url_pattern', 'http://symfony.com/?foo=%%s&amp;bar=%%d');
};
    

Дата обновления перевода 2023-01-20

Note

В связи с тем, как разрешаются параметры, вы не можете использовать их для построения путей в импорте динамически. Это означает, что что-то вроде этого работать не будет:

YAML
XML
PHP

        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) {
    $container->import('%kernel.project_dir%/somefile.yaml');
};
    

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

See also

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

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

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

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

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

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

config/packages/*.yaml (а також файли *.xml та *.php);
config/packages/<environment-name>/*.yaml (а також файли *.xml та *.php);
config/services.yaml (а також файли services.xml та services.php);
config/services_<environment-name>.yaml (а також файли services_<environment-name>.xml та services_<environment-name>.php).

Візьмемо пакет 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:

YAML
XML
PHP

        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) {
    $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)%. Значення цих опцій дозволяється під час виконання (лише один раз за запит, щоб не вплинути на этих опций разрешаются во время выполнения (только единожды за запрос, чтобы не повлиять на продуктивність).

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

YAML
XML
PHP

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

See also

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

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

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

Tip

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

Note

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

Caution

Майте на увазі, що скидання змісту змінних $_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.

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

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

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

Для покращення продуктивності, ви можете за бажанням виконати команду dump-env (доступна в Symfony Flex 1.2 та пізніше):

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

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

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

Замість визначення реальної змінної середовища, або її додавання в файл .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
    

6.2

Опція передачі імен змінних до debug:dotenv була представлена в Symfony 6.2.

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

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

---------------- -------------------------- ---------------------------------------------
 Ім'я             Значення за замочуванням   Реальне значення value
---------------- -------------------------- ---------------------------------------------
 APP_SECRET       n/a                        "471a62e2d601a8952deb186e44186cb3"
 FOO              "[1, "2.5", 3]"            n/a
 BAR              null                       n/a
---------------- -------------------------- ---------------------------------------------

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

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

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

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

        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, впровадьте параметри в якості аргументів їх конструкторів. Ви маєте впровадити їх чітко, тому що автоматичне впровадження сервісів не працює для параметрів:

YAML
XML
PHP

        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) {
    $container->parameters()
        ->set('app.contents_dir', '...');

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

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

YAML
XML
PHP

        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) {
    $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
22
23
        // src/Service/MessageGenerator.php
namespace App\Service;

// ...

use Symfony\Component\DependencyInjection\ParameterBag\ContainerBagInterface;

class MessageGenerator
{
    private $params;

    public function __construct(ContainerBagInterface $params)
    {
        $this->params = $params;
    }

    public function someMethod()
    {
        // отримайте будь-який параметр контейнеру з $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) {
    $security->firewall('main')
        ->pattern('^/*')
        ->lazy(true)
        ->anonymous();

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

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

Note

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

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

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

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