Конфигурация Symfony (и окружений)

Конфигурация Symfony (и окружений)

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

Конфигурация: config.yml

Главный файл конфигурации называется config.yml:

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    # app/config/config.yml
    imports:
        - { resource: parameters.yml }
        - { resource: security.yml }
        - { resource: services.yml }
    
    framework:
        secret:          '%secret%'
        router:          { resource: '%kernel.project_dir%/app/config/routing.yml' }
        # ...
    
    # Twig Configuration
    twig:
        debug:            '%kernel.debug%'
        strict_variables: '%kernel.debug%'
    
    # ...
    
  • XML
     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
    <!-- app/config/config.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"
        xmlns:twig="http://symfony.com/schema/dic/twig"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony
            http://symfony.com/schema/dic/symfony/symfony-1.0.xsd
            http://symfony.com/schema/dic/twig
            http://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <imports>
            <import resource="parameters.yml" />
            <import resource="security.yml" />
            <import resource="services.yml" />
        </imports>
    
        <framework:config secret="%secret%">
            <framework:router resource="%kernel.project_dir%/app/config/routing.xml" />
            <!-- ... -->
        </framework:config>
    
        <!-- Twig Configuration -->
        <twig:config debug="%kernel.debug%" strict-variables="%kernel.debug%" />
    
        <!-- ... -->
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    // app/config/config.php
    $this->import('parameters.yml');
    $this->import('security.yml');
    $this->import('services.yml');
    
    $container->loadFromExtension('framework', array(
        'secret' => '%secret%',
        'router' => array(
            'resource' => '%kernel.project_dir%/app/config/routing.php',
        ),
        // ...
    ));
    
    // Twig Configuration
    $container->loadFromExtension('twig', array(
        'debug'            => '%kernel.debug%',
        'strict_variables' => '%kernel.debug%',
    ));
    
    // ...
    

Большинство ключей высшего уровня вроде framework и twig - это конфигурация для конкретного пакета (т.е. FrameworkBundle и TwigBundle).

Далее в документации, все примеры конфигурации будут показаны в трех форматах (YAML, XML и PHP). YAML используется по умолчанию, но вы можете выбрать тот формат, который нравится вам больше всего. Разницы в производительности нет:

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

Источник и сброс конфигурации

Существует два способа узнать, какие ключи вы можете сконфигурировать:

  1. Использовать Раздел об источниках;
  2. Использовать команду config:dump-reference.

Например, если вы хотите сконфигурировать что-то в Twig, вы можете также увидеть пример сброса всех доступных опций конфигурации выполнив:

1
$ php bin/console config:dump-reference twig

Ключ импорта (imports): загрузка других файлов кофнигурации

Главный файл конфигурации Symfony - это app/config/config.yml. Но, для организации, он также загружает другие файлы конфигурации с помощью ключа imports:

  • YAML
    1
    2
    3
    4
    5
    6
    # app/config/config.yml
    imports:
        - { resource: parameters.yml }
        - { resource: security.yml }
        - { resource: services.yml }
    # ...
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    <!-- app/config/config.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
            http://symfony.com/schema/dic/services/services-1.0.xsd">
    
        <imports>
            <import resource="parameters.yml" />
            <import resource="security.yml" />
            <import resource="services.yml" />
        </imports>
    
        <!-- ... -->
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    // app/config/config.php
    $this->import('parameters.yml');
    $this->import('security.yml');
    $this->import('services.yml');
    
    // ...
    

Ключ imports работает очень схоже с PHP-функцией include(): читается и загружается содержимое parameters.yml, security.yml и services.yml. Вы также можете загрузить XML или PHP файлы.

Tip

Если ваше приложение использует нетрадиционные расширения файлов (например. ваши YAML-файлы имеют расширение .res), вы можете ясно установить тип файла с помощью опции type:

  • YAML
    1
    2
    3
    4
    # app/config/config.yml
    imports:
        - { resource: parameters.res, type: yml }
        # ...
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    <!-- app/config/config.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"
        xmlns:twig="http://symfony.com/schema/dic/twig"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony
            http://symfony.com/schema/dic/symfony/symfony-1.0.xsd
            http://symfony.com/schema/dic/twig
            http://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <imports>
            <import resource="parameters.res" type="yml" />
            <!-- ... -->
        </imports>
    </container>
    
  • PHP
    1
    2
    3
    // app/config/config.php
    $this->import('parameters.res', 'yml');
    // ...
    

Ключ параметров (parameter): Переменные

Еще один специальный ключ называется parameters: он используется для определения переменных, на которые можно ссылаться в любом файле конфигурации. Например, в config.yml, параметр locale определеятся, а потом на него ссылаются ниже под ключом framework:

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    # app/config/config.yml
    # ...
    
    parameters:
        locale: en
    
    framework:
        # ...
    
        # any string surrounded by two % is replaced by that parameter value
        default_locale:  "%locale%"
    
    # ...
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    <!-- app/config/config.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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony
            http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <!-- ... -->
        <parameters>
            <parameter key="locale">en</parameter>
        </parameters>
    
        <framework:config default-locale="%locale%">
            <!-- ... -->
        </framework:config>
    
        <!-- ... -->
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    // app/config/config.php
    // ...
    
    $container->setParameter('locale', 'en');
    
    $container->loadFromExtension('framework', array(
        'default_locale' => '%locale%',
        // ...
    ));
    
    // ...
    

Вы можете определять любые имена параметров, которые вы хотите, под ключом parameters в любом файле конфигурации.Чтобы сослаться на параметр, окружите его имя двумя символами процента, т.е. %locale%.

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

Чтобы узнать больше информации о параметрах, включая то, как ссылаться на них из контроллера см. Параметры сервис-контейнера.

Специальный файл parameters.yml

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

1
2
3
4
parameters:
    # ...
    database_user:      root
    database_password:  ~

Неудивительно, что на них ссылаются из config.yml и что они помогают конфигурировать DoctrineBundle и другие части Symfony:

  • YAML
    1
    2
    3
    4
    5
    6
    7
    # app/config/config.yml
    doctrine:
        dbal:
            driver:   pdo_mysql
            # ...
            user:     '%database_user%'
            password: '%database_password%'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    <!-- app/config/config.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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/doctrine
            http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
    
        <doctrine:config>
            <doctrine:dbal
                driver="pdo_mysql"
    
                user="%database_user%"
                password="%database_password%" />
        </doctrine:config>
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    // app/config/config.php
    $container->loadFromExtension('doctrine', array(
        'dbal' => array(
            'driver'   => 'pdo_mysql',
            // ...
    
            'user'     => '%database_user%',
            'password' => '%database_password%',
        ),
    ));
    

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

Из-за этого parameters.yml не передается вашей версии контроля. На самом деле, файл .gitignore, который установлен в Symfony по умолчанию, предотвращает такую передачу.

Однако файл parameters.yml.dist передан (с абстрактными значениями). Этот файл не читается Symfony: он просто является справочным, чтобы Symfony знал, какие параметры нужно определять в файле parameters.yml. Если вы добавите или удалите ключи к parameters.yml, добавьте или удалите их и из ``parameters.yml.dist`, чтобы оба файла всегда были синхронизированы.

Когда вы Устанавливаете существующий проект Symfony, вам понадобится создать файл parameters.yml используя переданный файл parameters.yml.dist в качестве источника. Чтобы помочь вам с этим, после того, как вы запустите composer install, скрипт Symfony автоматически создаст этот файл путем интерактивной просьбы предоставить значение для каждого параметра, определенного в parameters.yml.dist. Для того, чтобы получить более детальную информацию - или чтобы удалить или контролировать это поведение - см. документацию Оператор параметра Incenteev.

Окружения и другие файлы конфигурации

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

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

Как можно заставить одно приложение вести себя по-разному? С помощью окружений.

Вы наверное уже использовали окружение dev даже не зная об этом. После того, как вы введете приложение в действие, вы будете использовать окружение prod.

Чтобы узнать больше о том, как выполнять и контролировать каждое окружение, см. Окружения.

Продолжайте!

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

И многие другие темы.

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