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

В отличие от других фреймворков, Symfony не заставляет вас использовать конкретный формат для конфигурации приложения. Symfony позволяет вам выбирать между YAML, XML и PHP, и по всей документации Symfony, все примеры конфигурации будут показаны в этих трех форматах.

Между форматами нет практической разницы. На самом деле, Symfony транформирует и кэширует их все в PHP перед запуском приложения, так что между ними даже нет разницы в производиельности.

YAML используется по умолчанию при установке пакетов так как он лаконичный и очень читаемый. Вот основные преимущества и недостатки каждого формата:

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

Импортирование файлов конфигурации

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');

    // the third optional argument of import() is 'ignore_errors'
    // 'ignore_errors' установленный как 'not_found' silently тихо удаляет ошибки в случае если загруженный файл не существует
    $container->import('my_config_file.yaml', null, 'not_found');
    // 'ignore_errors' тихо удаляет все ошибки (включая неверный код и не найдено)
    $container->import('my_config_file.yaml', null, true);
};

// ...

Выбор активного окружения

Приложения Symfony имеют файл под названием .env, который находится в корневом каталоге проекта. Этот файл используется для определения значения переменных окружения и детально разъясняется далее в этой статье.

Откройте файл .env file (а лучше файл .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 file и выполните эту команду в производстве
$ APP_ENV=prod php bin/console command_name

Создание нового окружения

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

1. Создайте каталог конфигурации с тем же именем, что и у окружения (в этом случае, config/packages/staging/);
2. Добавьте необходимые файлы конфигурации в config/packages/staging/, чтобы определить поведение нового окружения. Symfony загружает файлы config/packages/*.yaml первыми, поэтому вам нужно сконфигурировать только разницу в этих файлах;
3. Выберите окружение staging, используя вариант окружения APP_ENV, как объяснялось в предыдущем разделе.

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

Конфигурация переменных окружения в файлах .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 при установке пакетов).

1
2
3

# database credentials
DB_USER=root
DB_PASS=pass # это секретный пароль

1
2

DB_USER=root
DB_PASS=${DB_USER}pass # добавьте пользователя в качестве префикса пароля

1
2

DB_USER=
DB_PASS=${DB_USER:-root}pass # приводит к DB_PASS=rootpass

1

START_TIME=$(date)

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 на вашем производственном сервере(ах) с вашими значениями производства.

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

1
2

# анализирует ВСЕ файлы .env и сбрасывает их финальные значения в .env.local.php
$ composer dump-env prod

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.

Хранение переменных окружения в других файлах

По умолчанию переменные окружения хранятся в файле .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 на системном
уровне (например, в конфигурации веб-сервера или в Dockerfile):

1
2

# .env (or .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). Читайте как переопределить переменные окружения , чтобы узнать больше об этом.

Шифрование переменных окружения (секреты)

Вместо определения реальной переменной окружения или ее добавления в файл .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

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

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

# выполните эту команду, чтобы показать все детали для конкретного env var:
$ php bin/console debug:container --env-var=FOO

Создание собственной логики загрузки переменных окружения

Вы можете реализовать свою собственную логику загрузки переменных окружения, если поведение Symfony по умолчанию

не соответствует вашим потребностям. Для этого создайте сервис, класс которого

реализует EnvVarLoaderInterface.

Допустим, у вас есть 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).

1
2
3
4
5

# .env (или .env.local)
APP_ENV=prod

# .env.prod (или .env.prod.local) - вернется к загрузчикам, которые вы определили
APP_ENV=