Управление конфигурацией с расширениями

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

Расширения должны реализовать ExtensionInterface и могут быть зарегистрированы в контейнере с помощью:

1

$container->registerExtension($extension);

Главная работа расширения проходит в методе load(). В методе load() вы можете загружать конфигурацию из одного или более файлов конфигурации, а также манипулировать определениями контейнера, используя методы, как показано в Как работать с объектами определений сервиса.

Методу load() передаётся свежий контейнер для установки, который потом слияется с контейнером, в котором он зарегистрирован. Это позволяет вам иметь несколько расширений, управляющих определениями контейнера независимо. Расширения не добавляют в конфигурацию контейнеров при добавлении, но обрабатываются при вызове метода контейнера compile().

Очень простое расширение может просто загружать файлы конфигурации в контейнер:

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

use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\ExtensionInterface;
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;

class AcmeDemoExtension implements ExtensionInterface
{
    public function load(array $configs, ContainerBuilder $container): void
    {
        $loader = new XmlFileLoader(
            $container,
            new FileLocator(__DIR__.'/../Resources/config')
        );
        $loader->load('services.xml');
    }

    // ...
}

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

Расширение должно указывать метод getAlias() для реализации интерфейса:

1
2
3
4
5
6
7
8
9
10
11

// ...

class AcmeDemoExtension implements ExtensionInterface
{
    // ...

    public function getAlias(): string
    {
        return 'acme_demo';
    }
}

Для файлов конфигурации YAML, указание псевдонима расширения в качестве ключа будет означать, что эти значения передаются методу расширения load():

1
2
3
4

# ...
acme_demo:
    foo: fooValue
    bar: barValue

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

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

use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;

$container = new ContainerBuilder();
$container->registerExtension(new AcmeDemoExtension);

$loader = new YamlFileLoader($container, new FileLocator(__DIR__));
$loader->load('config.yaml');

// ...
$container->compile();

Значения из этих разделов файлов конфигурации передаются в первый аргумент метода расширения load():

1
2
3
4
5

public function load(array $configs, ContainerBuilder $container): void
{
    $foo = $configs[0]['foo']; //fooValue
    $bar = $configs[0]['bar']; //barValue
}

Аргумент $configs - это массив, содержащий каждый отличный файл конфигурации, который был загружен в контейнер. Вы загружаете только один файл конфигурации в примере выше, но он всё равно будет в массиве. Массив будет выглядеть так:

1
2
3
4
5
6

[
    [
        'foo' => 'fooValue',
        'bar' => 'barValue',
    ],
]

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

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

use Symfony\Component\Config\Definition\Processor;
// ...

public function load(array $configs, ContainerBuilder $container): void
{
    $configuration = new Configuration();
    $processor = new Processor();
    $config = $processor->processConfiguration($configuration, $configs);

    $foo = $config['foo']; //fooValue
    $bar = $config['bar']; //barValue

    // ...
}

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

1
2
3
4
5
6
7
8
9

public function getXsdValidationBasePath(): string
{
    return __DIR__.'/../Resources/config/';
}

public function getNamespace(): string
{
    return 'http://www.example.com/symfony/schema/';
}

XML версия конфигурации будет выглядеть так:

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

<?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:acme-demo="http://www.example.com/schema/dic/acme_demo"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://www.example.com/schema/dic/acme_demo
        https://www.example.com/schema/dic/acme_demo/acme_demo-1.0.xsd"
>
    <acme-demo:config>
        <acme_demo:foo>fooValue</acme_demo:foo>
        <acme_demo:bar>barValue</acme_demo:bar>
    </acme-demo:config>
</container>

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

1
2
3
4
5
6
7
8
9
10

public function load(array $configs, ContainerBuilder $container): void
{
    $configuration = new Configuration();
    $processor = new Processor();
    $config = $processor->processConfiguration($configuration, $configs);

    $container->setParameter('acme_demo.FOO', $config['foo']);

    // ...
}

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

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

public function load(array $configs, ContainerBuilder $container): void
{
    $configuration = new Configuration();
    $processor = new Processor();
    $config = $processor->processConfiguration($configuration, $configs);

    $loader = new XmlFileLoader(
        $container,
        new FileLocator(__DIR__.'/../Resources/config')
    );
    $loader->load('services.xml');

    if ($config['advanced']) {
        $loader->load('advanced.xml');
    }
}

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

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

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

public function load(array $configs, ContainerBuilder $containerBuilder)
{
    // ...

    $containerBuilder->setParameter('acme_demo.database_user', $configs['db_user']);

    $containerBuilder->deprecateParameter(
        'acme_demo.database_user',
        'acme/database-package',
        '1.3',
        // по желанию, вы можете установить пользовательское сообщение об устаревании
        '"acme_demo.database_user" is deprecated, you should configure database credentials with the "acme_demo.database_dsn" parameter instead.'
    );
}

Устаревший параметр должен быть установлен до объявления его устаревшим. Иначе будет вызвано исключение ParameterNotFoundException.

1
2
3
4
5
6
7

use Symfony\Component\DependencyInjection\ContainerBuilder;

$container = new ContainerBuilder();
$extension = new AcmeDemoExtension();
$container->registerExtension($extension);
$container->loadFromExtension($extension->getAlias());
$container->compile();

Добавление к конфигурации, переданной расширению

Расширение может добавлять к конфигурации любого пакета перед вызовом метода load(), реализуя PrependExtensionInterface:

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

use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
// ...

class AcmeDemoExtension implements ExtensionInterface, PrependExtensionInterface
{
    // ...

    public function prepend(ContainerBuilder $container): void
    {
        // ...

        $container->prependExtensionConfig($name, $config);

        // ...
    }
}

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

Выполнение кода во время компиляции

Вы также можете выполнить пользовательский код во время компиляции, написав вашу собственную передачу компилятора. Реализовав CompilerPassInterface в вашем расширении, добавленный метод process() будет вызван во время компиляции:

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

// ...
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;

class AcmeDemoExtension implements ExtensionInterface, CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
       // ... сделать что-то во время компиляции
    }

    // ...
}

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

Параметрами и определениями контейнера можно манипулровать, используя методы, описанные в Как работать с объектами определений сервиса.

Частым случаем использования передач компилятора является поиск всех определений сервиса, имеющих определённый тег, для того, чтобы динамически вставлять каждый в какой-то другой сервис. См. раздел сервис-теги , чтобы увидеть пример.

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class CustomPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
       // ... сделать что-то во время компиляции
    }
}

1
2
3
4

use Symfony\Component\DependencyInjection\ContainerBuilder;

$container = new ContainerBuilder();
$container->addCompilerPass(new CustomPass());

1
2
3
4
5

// ...
$container->addCompilerPass(
    new CustomPass(),
    PassConfig::TYPE_AFTER_REMOVING
);

1
2
3
4
5
6
7
8

// ...
// FirstPass выполняется после SecondPass, так как его приоритет ниже
$container->addCompilerPass(
    new FirstPass(), PassConfig::TYPE_AFTER_REMOVING, 10
);
$container->addCompilerPass(
    new SecondPass(), PassConfig::TYPE_AFTER_REMOVING, 30
);

Сброс конфигурации для производительности

Использование файлов конфигурации для управления сервис-контейнером может быть намного проще для понимания, чем использовать PHP, когда существует уже множество сервисов. Эта лёгкость однако имеет свою цену, когда речь заходит о производительности, так как файлы конфигурации нужно анализировать, и из них строится конфигурация PHP. Процесс компиляции делает контейнер эффективнее, но забирает время на выполнение. Вы можете получить все преимущества,используя файлы конфигурации, а потом сбрасывая их и кешируя результирующую конфигурацию. PhpDumper делает сброс скомпилированного контенера простым:

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

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Dumper\PhpDumper;

$file = __DIR__ .'/cache/container.php';

if (file_exists($file)) {
    require_once $file;
    $container = new ProjectServiceContainer();
} else {
    $container = new ContainerBuilder();
    // ...
    $container->compile();

    $dumper = new PhpDumper($container);
    file_put_contents($file, $dumper->dump());
}

ProjectServiceContainer это данное классу сброшенного контейнера по умолчанию. Однако вы можете изменить его с опцией class, когда вы будете его сбрасывать:

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

// ...
$file = __DIR__ .'/cache/container.php';

if (file_exists($file)) {
    require_once $file;
    $container = new MyCachedContainer();
} else {
    $container = new ContainerBuilder();
    // ...
    $container->compile();

    $dumper = new PhpDumper($container);
    file_put_contents(
        $file,
        $dumper->dump(['class' => 'MyCachedContainer'])
    );
}

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

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

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

// ...

// основывается на чем-то в вашем проекте
$isDebug = ...;

$file = __DIR__ .'/cache/container.php';

if (!$isDebug && file_exists($file)) {
    require_once $file;
    $container = new MyCachedContainer();
} else {
    $container = new ContainerBuilder();
    // ...
    $container->compile();

    if (!$isDebug) {
        $dumper = new PhpDumper($container);
        file_put_contents(
            $file,
            $dumper->dump(['class' => 'MyCachedContainer'])
        );
    }
}

Это можно улучшить ещё, просто перекомпилировав контейнер в режиме отладки, если в его конфигурации были сделаны изменения, а не делая это по каждому запросу. Это можно сделать путём кеширования файлов источников, использованных для конфигурации контейнера, описаным в документации компонента Configuration "Кеширование, основанное на источниках".

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

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

// ...

// основываясь на чём-то в вашем проекте
$isDebug = ...;

$file = __DIR__ .'/cache/container.php';
$containerConfigCache = new ConfigCache($file, $isDebug);

if (!$containerConfigCache->isFresh()) {
    $container = new ContainerBuilder();
    // ...
    $container->compile();

    $dumper = new PhpDumper($container);
    $containerConfigCache->write(
        $dumper->dump(['class' => 'MyCachedContainer']),
        $container->getResources()
    );
}

require_once $file;
$container = new MyCachedContainer();

Теперь кешированный сброшенный контейнер используется невзирая на то, включен ли режим отладки. Разница заключается в том, что ConfigCache установлен в режим отладки вторым аргументом конструктора. Когда кеш не находится в режиме отладки, всегда будет исползован кешированный контейнер, если он существует. В режиме отладки, пишется дополнительный файл метаданных с помощью временных отметок всех файлов источников. Потом они проверяются, чтобы увидеть, не изменялись ли файлы, и если они изменялись, то кеш будет считаться просроченным.