Конфигураация

Конфигураация

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

Конфигурация, связанная с инфраструктурой

Best Practice

Определите опции конфигурации, связанной с инфраструктурой в файле app/config/parameters.yml.

Файл по умолчанию parameters.yml следует этой рекомендации и определяет опции, относящиеся к инфраструктуре БД и почтового сервера:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# app/config/parameters.yml
parameters:
    database_driver:   pdo_mysql
    database_host:     127.0.0.1
    database_port:     ~
    database_name:     symfony
    database_user:     root
    database_password: ~

    mailer_transport:  smtp
    mailer_host:       127.0.0.1
    mailer_user:       ~
    mailer_password:   ~

    # ...

Эти опции не определены внутри файла app/config/config.yml так как они не имеют ничего общего с поведением приложения. Другими словами, вашему приложению наплевать на локацию вашей БД или сертификаты для доступа к ней, если БД сконфигурирована корректно.

Каноничные параметры

Best Practice

Определите все параметры вашего приложения в файле app/config/parameters.yml.dist.

Symfony включает в себя файл конфигурации под названием parameters.yml.dist, который хранит каноничный список параметров конфигурации приложения.

Когда определяется новый параметр конфигурации приложения, вам также стоит добавить его в этот файл и отправить изменения вашей системе контроля версий. Далее, каждый раз, когда разрботчик обновляет проект или развёртывает его на сервере, Symfony будет проверять, существует ли разница между каноничным файлом parameters.yml.dist и вашим локальным файлом parameters.yml. Если разница есть, Symfony попросит вас предоставить значение для нового параметра и добавит его в ваш локальный файл parameters.yml.

Конфигурация, связанная с приложением

Best Practice

Определите опции конфигурации, связанные с поведением приложения в файле app/config/config.yml.

Файл config.yml содержит опции, используемые приложением для изменения его поведения, такие как отправка уведомлений по электронной почте, или включение переключателей функций. Определение этих значений в файле parameters.yml добавит дополнительный слой конфигурации, который не нужен, так каквам не нужно, чтобы эти значения конфигурации изменялись на каждом сервере.

Опции конфигурации, определённые в файле config.yml обычно отличаются от окружения к окружению. Поэтому Symfony уже включает в себя файлы app/config/config_dev.yml и app/config/config_prod.yml, чтобы вы могли переопределять конкретные значения для каждого окружения.

Константы против опций конфигурации

Одна из наиболее распространённых ошибок при определении конфигурации приложения - создавать новые опции для значений, которые никогда не изменяются, например, количество объектов для пронумерованных результатов.

Best Practice

Используйте константы для определния опций конфигурации, которые редко изменяются.

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

1
2
3
# app/config/config.yml
parameters:
    homepage.num_items: 10

Если вы делали что-то подобное в прошлом, то есть вероятность, что вам на самом деле никогда не нужно было изменять это значение. Создание опции конфигурации для значения, которое вы не собираетесь когда-либо конфигурировать просто бессмысленно. Мы рекомендуем определять эти значения в качестве констант в вашем приложении. Вы можете, например, определить константу NUM_ITEMS в сущности Post:

1
2
3
4
5
6
7
8
9
// src/AppBundle/Entity/Post.php
namespace AppBundle\Entity;

class Post
{
    const NUM_ITEMS = 10;

    // ...
}

Главное преимущество в определении констант заключается в том, что вы можете использовать их значения всюду в вашем приложении. При использовании параметров, они доступны только из мест с доступом к контейнеру Symfony.

Константы могут быть использованы, к примеру, в ваших шаблонах Twig, благодаря функции constant():

1
2
3
<p>
    Displaying the {{ constant('NUM_ITEMS', post) }} most recent results.
</p>

А сущности Doctrine и хранилища теперь могут с лёгкостью получать доступ к этим значениям, в то время, как к параметрам контейнера - нет:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
namespace AppBundle\Repository;

use Doctrine\ORM\EntityRepository;
use AppBundle\Entity\Post;

class PostRepository extends EntityRepository
{
    public function findLatest($limit = Post::NUM_ITEMS)
    {
        // ...
    }
}

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

Именование параметров

Best Practice

Имя ваших параметров конфигурации должно быть максимально коротким и включать в себя общий префикс для всего приложения.

Использование app. в качестве префикса ваших параметров является общей практикой для избежания коллизий Symfony и параметров сторонних пакетов и библиотек. Далее, используйте одно или два слова, чтобы описать цель параметра:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# app/config/config.yml
parameters:
    # не делайте так: 'dir' слишком общий и не несёт никакого значения
    app.dir: '...'
    # делайте так: короткие, но лёгкие для понимания имена
    app.contents_dir: '...'
    # можно использовать точки, нижние подчёркивания, дефисы или ничего из этого,
    # но всегда используйте один и тот же формат для всех параметров
    app.dir.contents: '...'
    app.contents-dir: '...'

Семантическая конфигурация: не делайте этого

Best Practice

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

Как объясняется в статье How to Load Service Configuration inside a Bundle, пакеты Symfony имеют два варианта того, как работать с конфигурацией: нормальная конфигурация сервиса через файл services.yml и семантическая конфигурация через специальный класс *Extension.

Несмотря на то, что семантическая конфигурация намного мощнее и предоставляет хорошие функции вроде валидации конфигурации, объём работы, необходимый для определения такой конфигурации не стоит того для пакетов, которые не будут распространяться в качестве сторонних пакетов.

Перемещение чувствительных опций полностью вне Symfony

При работе с чувствительными опциями вроде сертификатов БД, мы также рекомендуем вам хранить их вне проекта Symfony и делать их доступными через переменные окружения:

1
2
3
4
5
# app/config/config.yml
doctrine:
    dbal:
        # ...
        password: "%env(DB_PASSWORD)%"

New in version 3.2: Поддержка переменных окружения времени прогона через синтаксис %env(...)% была добавлена в Symfony 3.2. До версии 3.2, вам нужно было использовать специальные переменные SYMFONY__.

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.