Обработка массива $configs

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

Каждый раз, когда пользователь включает ключ acme_social (который является дополнительным именем ВЗ) в файле конфигурации, конфигурация под ним добавляется в массив конфигурация и передаётся методу load() вашего расширения (Symfony автоматически конвертирует XML и YAML в массив).

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

1
2
3
4
5
6
7
8

[
    [
        'twitter' => [
            'client_id' => 123,
            'client_secret' => 'your_secret',
        ],
    ],
]

Отметьте, что это массив массивов, а не просто плоский массив значений конфигурации. Это сделано специально, так как позволяет Symfony анализировать несколько источников конфигурации. Например, если acme_social появляется в другом файле конфигурации, скажем, config/packages/dev/acme_social.yaml, с другими значениями под ним, входящий массив может выглядеть так:

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

[
    // значения из config/packages/acme_social.yaml
        'twitter' => [
            'client_id' => 123,
            'client_secret' => 'your_secret',
        ],
    ],
    // values from config/packages/dev/acme_social.yaml
    [
        'twitter' => [
            'client_id' => 456,
        ],
    ],
]

Порядок двух массивов зависит от того, какой установлен первым.

Но не волнуйтесь! Компонент Symfony Config поможет вам объедиить эти значения, предоставит значения по умолчанию и даст пользователю ошибки валидации в плохой конфигурации. Вот, как это работает. Создайте класс Configuration в каталоге DependencyInjection и постройте дерево, определяющее структуру конфигурации вашего пакета.

Класс Configuration для обработки пробной конфигурации выглядит так:

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

// src/Acme/SocialBundle/DependencyInjection/Configuration.php
namespace Acme\SocialBundle\DependencyInjection;

use Symfony\Component\Config\Definition\Builder\TreeBuilder;
use Symfony\Component\Config\Definition\ConfigurationInterface;

class Configuration implements ConfigurationInterface
{
    public function getConfigTreeBuilder()
    {
        $treeBuilder = new TreeBuilder('acme_social');

        $treeBuilder->getRootNode()
            ->children()
                ->arrayNode('twitter')
                    ->children()
                        ->integerNode('client_id')->end()
                        ->scalarNode('client_secret')->end()
                    ->end()
                ->end() // twitter
            ->end()
        ;

        return $treeBuilder;
    }
}

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

1
2
3
4
5
6
7
8
9
10

// src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
public function load(array $configs, ContainerBuilder $container)
{
    $configuration = new Configuration();

    $config = $this->processConfiguration($configuration, $configs);

    // теперь у вас есть эти 2 ключа конфигурации
    // $config['twitter']['client_id'] and $config['twitter']['client_secret']
}

Метод processConfiguration() использует дерево конфигурации, которое вы определили в классе Configuration для валидации, нормализаци и слияния всех массивов конфигурации.

Теперь вы можете использовать переменную $config для изменения сервиса, предоставленного вашим пакетом. Например, представьте, что ваш пакет имеет следующий пример конфигурации:

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

<!-- src/Acme/SocialBundle/Resources/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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd"
>
    <services>
        <service id="acme.social.twitter_client" class="Acme\SocialBundle\TwitterClient">
            <argument></argument> <!-- will be filled in with client_id dynamically -->
            <argument></argument> <!-- will be filled in with client_secret dynamically -->
        </service>
    </services>
</container>

In your extension, you can load this and dynamically set its arguments:

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

// src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
// ...

use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;

public function load(array $configs, ContainerBuilder $container)
{
    $loader = new XmlFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config'));
    $loader->load('services.xml');

    $configuration = new Configuration();
    $config = $this->processConfiguration($configuration, $configs);

    $definition = $container->getDefinition('acme.social.twitter_client');
    $definition->replaceArgument(0, $config['twitter']['client_id']);
    $definition->replaceArgument(1, $config['twitter']['client_secret']);
}

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

// src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
namespace Acme\HelloBundle\DependencyInjection;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\HttpKernel\DependencyInjection\ConfigurableExtension;

class AcmeHelloExtension extends ConfigurableExtension
{
    // отметьте, что этот метод называетсят loadInternal, а не загрузка
    защищённой функции loadInternal(массив $mergedConfig, ContainerBuilder $container)
    {
        // ...
    }
}

1
2
3
4
5
6
7
8
9
10

public function load(array $configs, ContainerBuilder $container)
{
    $config = [];
    // позвольте источникам переопределить предыдущее установленное значение
    foreach ($configs as $subConfig) {
        $config = array_merge($config, $subConfig);
    }

    // ... теперь используйте чистый массив $config
}

Подготовьте ваше дерево конфигурации к XML

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

Выбор пространста имён XML

В XML, пространство имён XML используется для определения того, какие элементы принадлежат конфигурации конкретного пакета. Пространство имён возвращается из метода Extension::getNamespace(). По соглашению, пространство имён - это URL (он не должен быть валидным или в принципе сушествовать). По умолчанию, просранство имён для пакета - http://example.org/schema/dic/DI_ALIAS, где DI_ALIAS - дополнительное имя прямого внедрения расширения. Вы можете захотеть изменить это на более профессиональный URL:

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

// src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php

// ...
class AcmeHelloExtension extends Extension
{
    // ...

    public function getNamespace()
    {
        return 'http://acme_company.com/schema/dic/hello';
    }
}

Предоставление XML-схемы

XML имеет очень полезную функцию, под названием XML-схема. Она позволяет вам описать все возможные элементы и атрибуты, а также их значения, в Определении XML-схемы (xsd-файл). Этот XSD-файл используется интегрированной средой обработки для автозаполнения и использутется компонентом Configuration для валидации элементов.

Для того, чтобы использовать схему, файл XML-конфигурации должен предоставлять атрибут xsi:schemaLocation, указывающий на XSD-файл для определённого пространства имён XML. Это местоположение всегда начинается с пространства имён XML. Это пространство имён XML потом заменяется базовым путём XSD-валидации, возвращёнными из метода Extension::getXsdValidationBasePath(). Потом за этим пространством имён следует остальной путь из базового пути к самому файлу.

По соглашению, XSD-файл живёт в Resources/config/schema/, но вы можете разместить его где угодно. Вам стоит вернуть этот путь в качестве базового:

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

// src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php

// ...
class AcmeHelloExtension extends Extension
{
    // ...

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

Если предположить, что XSD-файл называется hello-1.0.xsd, то месторасположение схемы будет http://acme_company.com/schema/dic/hello/hello-1.0.xsd:

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

<!-- config/packages/acme_hello.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:acme-hello="http://acme_company.com/schema/dic/hello"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://acme_company.com/schema/dic/hello
        https://acme_company.com/schema/dic/hello/hello-1.0.xsd"
>
    <acme-hello:config>
        <!-- ... -->
    </acme-hello:config>

    <!-- ... -->
</container>