1. Документация
  2. Конфигурация Symfony (и окружений)

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

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

Конфигурация: config/packages/

Файл конфигурации каждого пакета можно найти в config/packages/. Например, пакет фреймворка конфигурируется в config/packages/framework.yaml:

  • YAML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
    # config/packages/framework.yaml
framework:
    secret: '%env(APP_SECRET)%'
    #default_locale: en
    #csrf_protection: ~
    #http_method_override: true
    #trusted_hosts: ~
    # https://symfony.com/doc/current/reference/configuration/framework.html#handler-id
    #session:
    #    # The native PHP session handler will be used
    #    handler_id: ~
    #esi: ~
    #fragments: ~
    php_errors:
        log: true
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:framework="http://symfony.com/schema/dic/framework"
    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
        http://symfony.com/schema/dic/framework http://symfony.com/schema/dic/framework/framework-1.0.xsd"
>
    <framework:config secret="%env(APP_SECRET)%">
        <framework:php-errors log="true" />
    </framework:config>
</container>
  • PHP
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    # config/packages/framework.php
$container->loadFromExtension('framework', [
    'secret' => '%env(APP_SECRET)%',
    //'default_locale' => 'en',
    //'csrf_protection' => null,
    //'http_method_override' => true,
    //'trusted_hosts' => null,
    // https://symfony.com/doc/current/reference/configuration/framework.html#handler-id
    //'session' => [
    //    // Будет использован родной обработчик сессий PHP
    //    'handler_id' => null,
    //],
    //'esi' => null,
    //'fragments' => null,
    'php_errors' => [
        'log' => true,
    ],
]);

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

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

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

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

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

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

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

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

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

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

Конфигурация имеет некоторые специальные ключи верхнего уровня. Один из них называется parameters: он используется для определения переменных, на которые можно сослаться в любом другом файле конфигурации. Например, когда вы устанавливаете пакет перевода, параметр locale добавляется в config/services.yaml:

  • YAML
    1
2
3
4
5
    # config/services.yaml
parameters:
    locale: en

# ...
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
    <!-- 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
        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>

    <!-- ... -->
</container>
  • PHP
    1
2
3
    // config/services.php
$container->setParameter('locale', 'en');
// ...

На этот параметр потом ссылаются в конфигурации фреймворка в config/packages/translation.yaml:

  • YAML
    1
2
3
4
5
6
    # config/packages/translation.yaml
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
    <!-- config/packages/translation.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">

    <!-- любая строка, окружённая двумя % заменяется этим значением параметра -->
    <framework:config default-locale="%locale%">
        <!-- ... -->
    </framework:config>
</container>
  • PHP
    1
2
3
4
5
6
7
    // config/packages/translation.php
$container->loadFromExtension('framework', array(
    // любая строка, окружённая двумя % заменяется этим значением параметраe
    'default_locale' => '%locale%',

    // ...
));

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

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

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

Файл .env и переменные окружения

Также существует загружаемый файл .env. Его содержание становится переменными окружения в окружении разработки, что облегчает ссылание на переменные окружения в вашем коде. Когда вы устанавливаете пакеты, в этот файл добавляется больше переменных окружения. Но вы также можете добавлять ваши собственные переменные.

На переменные окружения можно сослатьсяв любых других файлах конфигурации, используя специальный синтаксис. Например, если установите пакет doctrine, то у вас будет переменная окружения под названием DATABASE_URL в вашем файле .env. Ссылка на это находится внутри config/packages/doctrine.yaml:

1
2
3
4
5
6
7
# config/packages/doctrine.yaml
doctrine:
    dbal:
        url: '%env(DATABASE_URL)%'

        # решеие: префикс разрешит параметры *внутри* переменной окружения
        # url: '%env(resolve:DATABASE_URL)%'

Чтобы узнать больше о переменных окружений, см. Referencing Env Vars in Configuration Files.

Файл .env особенный, так как он определяет значения, которые обычно изменяются на каждом сервере. Например, сертификаты БД на вашей локальной машине разработки могут отличаться от тех, что у ваших коллег. Поэтому этот файл не фиксируется в общем хранилище и сохраняется только на вашей машине. Даже больше, файл .gitignore, который поставляется с Symfony, предотвращает его фиксацию.

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

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

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

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

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

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

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

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

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

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

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