Конфигурация 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. Однако, вы быстро к ним привыкнете и вам редко когда нужно будет менять эти файлы после утсановки пакета.

Параметры конфигурации¶

Иногда одино и то же значение конфигурации используется в нескольких файлах конфигурации. Вместо его повторения, вы можете определить его как “параметр”, что является чем-то вроде повторно используемого значения конфигурации. По соглашению, параметры определяются под ключом parameters в файле config/services.yaml:

1
2
3

<parameter key="app.admin_email">
    [email protected]
</parameter>

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

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

Окружения конфигурации¶

У вас есть только одно приложение, но понимаете вы это или нет, вам нужно, чтобы оно вело себя по-разному при разных обстоятельствах:

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

Файлы, хранящиеся в config/packages/ используются Symfony для конфигурации сервисов приложения. Другими словами, вы можете изменить поведение приложения, изменив то, какие файлы конфигурации загружаются. В этом заключается идея окружений конфигурации Symfony.

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

1. config/packages/*.yaml (а также файлы *.xml и *.php);
2. config/packages/<environment-name>/*.yaml (а также файлы *.xml и *.php);
3. config/services.yaml (а также файлы services.xml и services.php);
4. 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/.

1
2

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

1
2
3
4
5

# Используйте окружение, определенное в файле .env
$ php bin/console command_name

# Игнорируйте файл .env file и выполните эту команду в производстве
$ APP_ENV=prod php bin/console command_name

Конфигурация, основанная на переменных окружаения¶

Использование `переменных окружения`_ (или сокращенно “env vars”) - это распространенная практика для конфигурации опций, которые зависят от того, где запускается приложение (например, идентификационные данные БД обычно отличаются в производстве и на вашей локальной машине). Если значения чувствительны, вы даже можете зашифровать из как секретные.

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

Этот пример показывает, как вы можете сконфигурировать соединение БД, используя переменную окружения:

Чтобы определить значение любой переменной окружения, у вас есть несколько вариантов:

• Добавить значение к файлу .env;
• Зашифровать значение как секрет;
• Установить значение как реальную переменную окружения в вашей оболочке или веб-сервере.

1
2

# .env
DATABASE_URL="mysql://db_user:[email protected]:3306/db_name"

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 # results in DB_PASS=rootpass

1

START_TIME=$(date)

1

$ source .env

1
2

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

1
2

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

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

$ 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
------------ ---------- ---------- ------

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

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

---------------- ----------------- ---------------------------------------------
 Name             Default value     Real value
---------------- ----------------- ---------------------------------------------
 APP_SECRET       n/a               "471a62e2d601a8952deb186e44186cb3"
 FOO              "[1, "2.5", 3]"   n/a
 BAR              null              n/a
---------------- ----------------- ---------------------------------------------

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

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

Доступ к параметрам конфигурации¶

Контроллеры и сервисы могут получить доступ ко всем параметрам конфигурации. Это включает в себя как параметры, определенные вами defined by yourself, так и параметры, созданные пакетами. Выполните следующую команду, чтобы увидеть все параметры, существующие в вашем приложении:

1

$ php bin/console debug:container --parameters

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

// 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, внедрите параметры в качестве аргументов их конструкторов. Вы должены внедрить их ясно, потому что автоматическое внедрение сервисов не работает для параметров:

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

Наконец, если какому-то сервису нужен доступ ко множеству параметров, вместо внедрения каждого из них отдельно, вы можете внедрить все параметры приложения одномоментно добавив подсказки при вводе кода к любому из аргументов конструктора с ContainerBagInterface:

// 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:

// 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']);
};

Не останавливайтесь!¶

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

• Forms
• Databases and the Doctrine ORM
• Service Container
• Security
• Sending Emails with Mailer
• Logging

И все другие темы, связанные с конфигурацией: