Як працювати з тегами сервісів

Дата оновлення перекладу 2024-06-06

Як працювати з тегами сервісів

Теги сервісів - це спосіб повідомити Symfony або іншим стороннім пакетам, що ваш сервіс має бути зареєстрований якимось особливим чином. Візьміть наступний приклад:

        1
2
3
4
        # config/services.yaml
services:
    App\Twig\AppExtension:
        tags: ['twig.extension']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- 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="App\Twig\AppExtension">
            <tag name="twig.extension"/>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Twig\AppExtension;

return function(ContainerConfigurator $container): void {
    $services = $container->services();

    $services->set(AppExtension::class)
        ->tag('twig.extension');
};
    

Сервіси з тегом twig.extension збираються під час ініціалізації TwigBundle і додаються в Twig як розширення.

Інші теги використовуються для інтеграції ваших сервісів у інші системи. Щоб побачити всі доступні теги у базовому фреймворку Symfony, перегляньте Вбудовані теги сервісів Symfony. Кожний з них має різний ефект у вашому сервісі, і багато тегів вимагають додаткових аргументів (окрім параметра name).

Для більшості користувачів - це все, що вам треба знати. Якщо ви хочете заглибитися у вивчення того, як створити ваші власти користувацькі теги, продовжуйте читати.

Автоконфігурація тегів

Якщо ви увімкнули автоконфігурацію , тоді деякі теги застосовуються для вас автоматично. Це так для тегу twig.extension: контейнер бачить, що ваш клас розширює AbstractExtension (точніше, реалізує ExtensionInterface), і додає тег для вас.

Якщо ви хочете застосовувати теги автоматично для ваших власних сервісів, використовуйте опцію _instanceof:

        1
2
3
4
5
6
7
8
        # config/services.yaml
services:
    # ця конфігурація застосовується лише до сервісів, створених цим файлом
    _instanceof:
        # сервіси, класи яких є екземплярами CustomInterface будуть теговані автоматично
        App\Security\CustomInterface:
            tags: ['app.custom_tag']
    # ...
    

        1
2
3
4
5
6
7
8
9
10
11
        <!-- 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>
        <!-- ця конфігурація застосовується лише до сервісів, створених цим файлом -->
        <instanceof id="App\Security\CustomInterface" autowire="true">
            <!-- сервіси, класи яких є екземплярами CustomInterface будуть теговані автоматично -->
            <tag name="app.custom_tag"/>
        </instanceof>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Security\CustomInterface;

return function(ContainerConfigurator $container): void {
    $services = $container->services();

    // ця конфігурація застосовується лише до сервісів, створених цим файлом
    $services
        ->instanceof(CustomInterface::class)
            // сервіси, класи яких є екземплярами CustomInterface будуть теговані автоматично
            ->tag('app.custom_tag');
};
    

Caution

Якщо ви використовуєте конфігурацію PHP, вам потрібно викликати instanceof перед будь-якою реєстрацією сервісу, щоб переконатися, що теги застосовано правильно.

Також можливо використати атрибут #[AutoconfigureTag] прямо у базовому класі чи інтерфейсі:

        1
2
3
4
5
6
7
8
9
10
        // src/Security/CustomInterface.php
namespace App\Security;

use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag('app.custom_tag')]
interface CustomInterface
{
    // ...
}
    

Tip

Якщо вам потрібно більше можливостей для автоконфігурації екземплярів вашого базового класу, на кшталт їхньої лінивості, їх повʼязаності або викликів, наприклад, ви можете покластися на атрибут Autoconfigure.

Для більш просунутих потреб, ви можете визначити автоматичні теги, використовуючи метод registerForAutoconfiguration().

У додатку Symfony, викличте цей метод у вашому класі ядра:

        1
2
3
4
5
6
7
8
9
10
11
12
        // src/Kernel.php
class Kernel extends BaseKernel
{
    // ...

    protected function build(ContainerBuilder $container): void
    {
        $container->registerForAutoconfiguration(CustomInterface::class)
            ->addTag('app.custom_tag')
        ;
    }
}
    

У пакеті Symfony, викличте цей метод у методі load() класса расширения пакета:

        1
2
3
4
5
6
7
8
9
10
11
12
        // src/DependencyInjection/MyBundleExtension.php
class MyBundleExtension extends Extension
{
    // ...

    public function load(array $configs, ContainerBuilder $container): void
    {
        $container->registerForAutoconfiguration(CustomInterface::class)
            ->addTag('app.custom_tag')
        ;
    }
}
    

Реєстрація автоконфігурації не обмежується інтерфейсами. Існує можливість використовувати атрибути PHP для автоконфігурації сервісів за допомогою метода registerAttributeForAutoconfiguration():

        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
30
31
32
33
34
35
        // src/Attribute/SensitiveElement.php
namespace App\Attribute;

#[\Attribute(\Attribute::TARGET_CLASS)]
class SensitiveElement
{
    public function __construct(
        private string $token,
    ) {
    }

    public function getToken(): string
    {
        return $this->token;
    }
}

// src/Kernel.php
use App\Attribute\SensitiveElement;

class Kernel extends BaseKernel
{
    // ...

    protected function build(ContainerBuilder $container): void
    {
        // ...

        $container->registerAttributeForAutoconfiguration(SensitiveElement::class, static function (ChildDefinition $definition, SensitiveElement $attribute, \ReflectionClass $reflector): void {
            // Застосувати тег 'app.sensitive_element' до всіх класів з атрибутом SensitiveElement
            // та доєднати значення токена до тегу
            $definition->addTag('app.sensitive_element', ['token' => $attribute->getToken()]);
        });
    }
}
    

Ви також можете зробити атрибути доступними в методах. Щоб зробити це, оновіть попередній приклад і додайте Attribute::TARGET_METHOD:

        1
2
3
4
5
6
7
8
        // src/Attribute/SensitiveElement.php
namespace App\Attribute;

#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD)]
class SensitiveElement
{
    // ...
}
    

Далі, оновіть виклик registerAttributeForAutoconfiguration(), щоб він підтримував ReflectionMethod:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
        // src/Kernel.php
use App\Attribute\SensitiveElement;

class Kernel extends BaseKernel
{
    // ...

    protected function build(ContainerBuilder $container): void
    {
        // ...

        $container->registerAttributeForAutoconfiguration(SensitiveElement::class, static function (
            ChildDefinition $definition,
            SensitiveElement $attribute,
            // оновити тип обʼєднання для підтримки багатьох типів відображення
            // ви також можете використати інтерфейс "\Reflector"
            \ReflectionClass|\ReflectionMethod $reflector): void {
                if ($reflection instanceof \ReflectionMethod) {
                    // ...
                }
            }
        );
    }
}
    

Tip

Ви також можете визначити атрибут, щоб він був використовуваним у властивостях та параметрах за допомогою Attribute::TARGET_PROPERTY та Attribute::TARGET_PARAMETER; потім підтримайте ReflectionProperty та ReflectionParameter у вашому викличному registerAttributeForAutoconfiguration().

Створення користувацьких тегів

Теги самі по собі не змінюють функціональність ваших сервісів ніяким чином. Але якщо ви захочете, ви можете попросити у будівельника контейнера список всіх сервісів, які були теговані якимось конкретним тегом. Це корисно у пропусках компілятора, де можете знайти ці сервіси та використати або змінити їх якимось чином.

Наприклад, якщо ви використовуєте Swift Mailer, то ви можете уявити, що ви хочете реалізувати "транспортний ланцюжок", який є колекцією класів, що реалізують \Swift_Transport. Використовуючи ланцюжок, ви захочете, щоб Swift Mailer спробував декілька способів передачі повідомлення, поки один з них не спрацює.

Спочатку визначте клас TransportChain:

        1
2
3
4
5
6
7
8
9
10
11
12
        // src/Mail/TransportChain.php
namespace App\Mail;

class TransportChain
{
    private array $transports = [];

    public function addTransport(\MailerTransport $transport): void
    {
        $this->transports[] = $transport;
    }
}
    

Потім визначте ланцюжок як сервіс:

        1
2
3
        # config/services.yaml
services:
    App\Mail\TransportChain: ~
    

        1
2
3
4
5
6
7
8
9
10
11
        <!-- 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="App\Mail\TransportChain"/>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Mail\TransportChain;

return function(ContainerConfigurator $container): void {
    $services = $container->services();

    $services->set(TransportChain::class);
};
    

Визначте сервіси з користувацьким тегом

Тепер ви можете захотіти, щоб декілька з класів \Swift_Transport були інстанційовані та додані у ланцюжок автоматично, використовуючи метод addTransport(). Наприклад, ви можете додати наступні транспорти як сервіси:

        1
2
3
4
5
6
7
8
        # config/services.yaml
services:
    MailerSmtpTransport:
        arguments: ['%mailer_host%']
        tags: ['app.mail_transport']

    MailerSendmailTransport:
        tags: ['app.mail_transport']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        <!-- 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="MailerSmtpTransport">
            <argument>%mailer_host%</argument>

            <tag name="app.mail_transport"/>
        </service>

        <service id="MailerSendmailTransport">
            <tag name="app.mail_transport"/>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return function(ContainerConfigurator $container): void {
    $services = $container->services();

    $services->set(\MailerSmtpTransport::class)
        ->args([param('mailer_host')])
        ->tag('app.mail_transport')
    ;

    $services->set(\MailerSendmailTransport::class)
        ->tag('app.mail_transport')
    ;
};
    

Відмітьте, що кожному сервісу було надано тег під назвою app.mail_transport. Це користувацький тег, який ви будете використовувати у вашому пропуску компілятора. Пропуск компілятора - це те, що надає цьому тегу якийсь "сенс".

Створіть передачу компілятора

Тепер ви можете використати передачу компілятора , щоб запитати у контейнера будь-які сервіси з тегом app.mail_transport:

        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
        // src/DependencyInjection/Compiler/MailTransportPass.php
namespace App\DependencyInjection\Compiler;

use App\Mail\TransportChain;
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Reference;

class MailTransportPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        // завжди спочатку перевіряйте, чи визначений первинний сервіс
        if (!$container->has(TransportChain::class)) {
            return;
        }

        $definition = $container->findDefinition(TransportChain::class);

        // знайти всі ID сервісів з тегом app.mail_transport
        $taggedServices = $container->findTaggedServiceIds('app.mail_transport');

        foreach ($taggedServices as $id => $tags) {
            // додайте транспортний сервіс у сервіс ChainTransport
            $definition->addMethodCall('addTransport', [new Reference($id)]);
        }
    }
}
    

Зареєструйте передачу у контейнері

Для того, щоб запустити передачу компілятора, коли контейнер буде скомпільований, вам треба додати передачу компілятора у контейнер у розширення пакета або з вашого ядра:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        // src/Kernel.php
namespace App;

use App\DependencyInjection\Compiler\MailTransportPass;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;
// ...

class Kernel extends BaseKernel
{
    // ...

    protected function build(ContainerBuilder $container): void
    {
        $container->addCompilerPass(new MailTransportPass());
    }
}
    

Tip

При реалізації CompilerPassInterface у розширенні сервісу, вам не треба реєструвати його. Дивіться документацію компонентів , щоб дізнатися більше інформації.

Додавання додаткових атрибутів у теги

Іноді вам буде необхідна додаткова інформація про кожний сервіс, який було теговано вашим тегом. Наприклад, ви можете захотіти додати додаткове ім'я кожному члену транспортного ланцюжка.

Спочатку змініть клас TransportChain:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        class TransportChain
{
    private array $transports = [];

    public function addTransport(\MailerTransport $transport, $alias): void
    {
        $this->transports[$alias] = $transport;
    }

    public function getTransport($alias): ?\MailerTransport
    {
        return $this->transports[$alias] ?? null;
    }
}
    

Як ви бачите, коли викликається addTransport(), потрібний не тільки об'єкт Swift_Transport, але також додаткове ім'я рядка для цього транспорту. Тоді як ви можете дозволити кожному тегованому транспортному сервісу також постачати додаткове ім'я?

Щоб відповісти на це запитання, змініть оголошення сервісу:

        1
2
3
4
5
6
7
8
9
10
        # config/services.yaml
services:
    MailerSmtpTransport:
        arguments: ['%mailer_host%']
        tags:
            - { name: 'app.mail_transport', alias: 'smtp' }

    MailerSendmailTransport:
        tags:
            - { name: 'app.mail_transport', alias: ['sendmail', 'anotherAlias']}
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
        <!-- 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="MailerSmtpTransport">
            <argument>%mailer_host%</argument>

            <tag name="app.mail_transport" alias="smtp"/>
        </service>

        <service id="MailerSendmailTransport">
            <tag name="app.mail_transport">
                <attribute name="alias">
                    <attribute name="0">sendmail</attribute>
                    <attribute name="1">anotherAlias</attribute>
                </attribute>
            </tag>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return function(ContainerConfigurator $container): void {
    $services = $container->services();

    $services->set(\MailerSmtpTransport::class)
        ->args([param('mailer_host')])
        ->tag('app.mail_transport', ['alias' => 'smtp'])
    ;

    $services->set(\MailerSendmailTransport::class)
        ->tag('app.mail_transport', ['alias' => ['sendmail', 'anotherAlias']])
    ;
};
    

Tip

Атрибут name використовується за замовчуванням для визначення імені тегу. Якщо ви хочете додати атрибут name до якогось тегу у форматах XML або YAML, вам потрібно використовувати цей спеціальний синтаксис:

        1
2
3
4
5
6
7
8
9
        # config/services.yaml
services:
    MailerSmtpTransport:
        arguments: ['%mailer_host%']
        tags:
            # це тег з імʼям 'app.mail_transport'
            - { name: 'app.mail_transport', alias: 'smtp' }
            # це тег з імʼям 'app.mail_transport' з двома атрибутами ('name' та 'alias')
            - app.mail_transport: { name: 'arbitrary-value', alias: 'smtp' }
    

Tip

У форматі YAML ви можете надати тег в якості простого рядка, якщо вам не потрібно вказувати додаткові атрибути. Наступні визначення є еквівалентними.

        1
2
3
4
5
6
7
8
9
10
11
12
        # config/services.yaml
services:
    # Компактний синтасис
    Swift_SendmailTransport:
        class: \Swift_SendmailTransport
        tags: ['app.mail_transport']

    # Розширений синтаксис
    Swift_SendmailTransport:
        class: \Swift_SendmailTransport
        tags:
            - { name: 'app.mail_transport' }
    

Відмітьте, що ви додали спільний ключ alias до тегу. Щоб дійсно використати його, оновіть компілятор:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
        use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Reference;

class TransportCompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        // ...

        foreach ($taggedServices as $id => $tags) {

            // сервіс може мати один і той самий тег двічі
            foreach ($tags as $attributes) {
                $definition->addMethodCall('addTransport', [
                    new Reference($id),
                    $attributes['alias'],
                ]);
            }
        }
    }
}
    

Подвійний цикл може бути заплутаним. Це тому, що сервіс може мати більше одного тегу. Ви тегуєте сервіс двічі або більше за допомогою тегу app.mail_transport. Другий цикл foreach повторює набір тегів app.mail_transport для поточного сервісу і дає вам атрибути.

Посилайтеся на теговані сервіси

Symfony надає скорочення для впровадження всіх сервісів, тегованих конкретним тегом, що часто потрібно у деяких додатках, щоб вам не потрібно було підключати пропуск компілятора лише для цього.

Розгляньте наступний клас HandlerCollection, де ви хочете впровадити всі сервіси, що мають тег app.handler, у його аргумент конструктора:

        1
2
3
4
5
6
7
8
9
        // src/HandlerCollection.php
namespace App;

class HandlerCollection
{
    public function __construct(iterable $handlers)
    {
    }
}
    

Symfony дозволяє вам впроваджувати сервіси, використовуючи конфігурацію YAML/XML/PHP або прямо через атрибути PHP:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // src/HandlerCollection.php
namespace App;

use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;

class HandlerCollection
{
    public function __construct(
        // атрибут має бути застосований прямо в аргументі для автомонтування
        #[TaggedIterator('app.handler')] iterable $handlers
    ) {
    }
}
    

        1
2
3
4
5
6
7
8
9
10
11
12
        # config/services.yaml
services:
    App\Handler\One:
        tags: ['app.handler']

    App\Handler\Two:
        tags: ['app.handler']

    App\HandlerCollection:
        # впровадити всі сервіси, які мають тег app.handler, як перший аргумент
        arguments:
            - !tagged_iterator app.handler
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
        <!-- 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="App\Handler\One">
            <tag name="app.handler"/>
        </service>

        <service id="App\Handler\Two">
            <tag name="app.handler"/>
        </service>

        <service id="App\HandlerCollection">
            <!-- впровадити всі сервіси, які мають тег app.handler, як перший аргумент -->
            <argument type="tagged_iterator" tag="app.handler"/>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return function(ContainerConfigurator $container): void {
    $services = $container->services();

    $services->set(App\Handler\One::class)
        ->tag('app.handler')
    ;

    $services->set(App\Handler\Two::class)
        ->tag('app.handler')
    ;

    $services->set(App\HandlerCollection::class)
        // впровадити всі сервіси, які мають тег app.handler, як перший аргумент
        ->args([tagged_iterator('app.handler')])
    ;
};
    

Note

Деякі IDE видадуть помилку при використанні #[TaggedIterator] разом з просуванням PHP-конструктора: «Атрибут не може бути застосований до властивості, оскільки вона не містить прапорець “Attribute::TARGET_PROPERTY”». Причина в тому, що ці аргументи конструктора є одночасно параметрами і властивостями класу.
Ви можете сміливо ігнорувати це повідомлення про помилку.

Якщо з якоїсь причини вам потрібно виключити один або більше сервісів при використання тегованого ітератору, додайте опцію exclude:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // src/HandlerCollection.php
namespace App;

use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;

class HandlerCollection
{
    public function __construct(
        #[TaggedIterator('app.handler', exclude: ['App\Handler\Three'])]
        iterable $handlers
    ) {
    }
}
    

        1
2
3
4
5
6
7
8
9
10
11
        # config/services.yaml
services:
    # ...

    # Це сервіс, який ми хочемо виключити, навіть якщо додано тег 'app.handler'
    App\Handler\Three:
        tags: ['app.handler']

    App\HandlerCollection:
        arguments:
            - !tagged_iterator { tag: app.handler, exclude: ['App\Handler\Three'] }
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        <!-- 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>
        <!-- ... -->

        <!-- Це сервіс, який ми хочемо виключити, навіть якщо додано тег 'app.handler' -->
        <service id="App\Handler\Three">
            <tag name="app.handler"/>
        </service>

        <service id="App\HandlerCollection">
            <!-- впровадити всі сервіси, які мають тег app.handler, як перший аргумент -->
            <argument type="tagged_iterator" tag="app.handler">
                <exclude>App\Handler\Three</exclude>
            </argument>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return function(ContainerConfigurator $containerConfigurator) {
    $services = $containerConfigurator->services();

    // ...

    // Це сервіс, який ми хочемо виключити, навіть якщо додано тег 'app.handler'
    $services->set(App\Handler\Three::class)
        ->tag('app.handler')
    ;

    $services->set(App\HandlerCollection::class)
        // впровадити всі сервіси, які мають тег app.handler, як перший аргумент
        ->args([tagged_iterator('app.handler', exclude: [App\Handler\Three::class])])
    ;
};
    

У випадку, якщо сервіс, що посилається, сам має тег, який використовується у тегованому ітераторі, він автоматично виключається з впровадженого ітератора. Таку поведінку можна вимкнути, встановивши опцію exclude_self як false:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // src/HandlerCollection.php
namespace App;

use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;

class HandlerCollection
{
    public function __construct(
        #[TaggedIterator('app.handler', exclude: ['App\Handler\Three'], excludeSelf: false)]
        iterable $handlers
    ) {
    }
}
    

        1
2
3
4
5
6
7
8
9
10
11
        # config/services.yaml
services:
    # ...

    # Цей сервіс ми хочемо виключити, навіть якщо додано тег 'app.handler'
    App\Handler\Three:
        tags: ['app.handler']

    App\HandlerCollection:
        arguments:
            - !tagged_iterator { tag: app.handler, exclude: ['App\Handler\Three'], exclude_self: false }
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        <!-- 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>
        <!-- ... -->

        <!-- Цей сервіс ми хочемо виключити, навіть якщо додано тег 'app.handler' -->
        <service id="App\Handler\Three">
            <tag name="app.handler"/>
        </service>

        <service id="App\HandlerCollection">
            <!-- впровадити всі сервіси, з тегом app.handler в якості першого аргумента -->
            <argument type="tagged_iterator" tag="app.handler" exclude-self="false">
                <exclude>App\Handler\Three</exclude>
            </argument>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return function(ContainerConfigurator $containerConfigurator) {
    $services = $containerConfigurator->services();

    // ...

    // Цей сервіс ми хочемо виключити, навіть якщо додано тег 'app.handler'
    $services->set(App\Handler\Three::class)
        ->tag('app.handler')
    ;

    $services->set(App\HandlerCollection::class)
        // впровадити всі сервіси, з тегом app.handler в якості першого аргумента
        ->args([tagged_iterator('app.handler', exclude: [App\Handler\Three::class], excludeSelf: false)])
    ;
};
    

Теговані сервіси з пріоритетністю

Теговані сервіси можуть бути пріоритизовані з використанням атрибута priority. Пріоритетність - це додаткове або від'ємне ціле число, яке за замовчуванням дорівнює 0. Чим більше число, тим раніше буде знайдено тегований сервіс у колекції:

        1
2
3
4
5
        # config/services.yaml
services:
    App\Handler\One:
        tags:
            - { name: 'app.handler', priority: 20 }
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- 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="App\Handler\One">
            <tag name="app.handler" priority="20"/>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Handler\One;

return function(ContainerConfigurator $container): void {
    $services = $container->services();

    $services->set(One::class)
        ->tag('app.handler', ['priority' => 20])
    ;
};
    

Іншою опцією. яка особливо корисна при використанні автоконфігурації тегів, є реалізація статичного методу getDefaultPriority() у самому сервісі:

        1
2
3
4
5
6
7
8
9
10
        // src/Handler/One.php
namespace App\Handler;

class One
{
    public static function getDefaultPriority(): int
    {
        return 3;
    }
}
    

Якщо ви хочете мати інший метод, який визначатиме пріоритетність, (наприклад, getPriority() замість getDefaultPriority()), ви можете визначити його у конфігурації сервісу збору:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // src/HandlerCollection.php
namespace App;

use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;

class HandlerCollection
{
    public function __construct(
        #[TaggedIterator('app.handler', defaultPriorityMethod: 'getPriority')]
        iterable $handlers
    ) {
    }
}
    

        1
2
3
4
5
6
        # config/services.yaml
services:
    App\HandlerCollection:
        # впровадити всі сервіси з тегом app.handler в якості першого аргументу
        arguments:
            - !tagged_iterator { tag: app.handler, default_priority_method: getPriority }
    

        1
2
3
4
5
6
7
8
9
10
11
12
        <!-- 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="App\HandlerCollection">
            <argument type="tagged_iterator" tag="app.handler" default-priority-method="getPriority"/>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;

return function (ContainerConfigurator $container): void {
    $services = $container->services();

    // ...

    $services->set(App\HandlerCollection::class)
        ->args([
            tagged_iterator('app.handler', null, null, 'getPriority'),
        ])
    ;
};
    

Теговані сервіси з індексом

За замовчуванням теговані сервіси індексуються за їхніми ідентифікаторами. Ви можете змінити цю поведінку за допомогою двох опцій тегованого ітератора (index_by і default_index_method), які можуть використовуватися окремо або разом.

Опція `index_by` / `indexAttribute`

Ця опція визначає назву опції/атрибуту, який зберігає значення, що використовується для індексації сервісів:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // src/HandlerCollection.php
namespace App;

use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;

class HandlerCollection
{
    public function __construct(
        #[TaggedIterator('app.handler', indexAttribute: 'key')]
        iterable $handlers
    ) {
    }
}
    

        1
2
3
4
5
6
7
8
9
10
11
12
        # config/services.yaml
services:
    App\Handler\One:
        tags:
            - { name: 'app.handler', key: 'handler_one' }

    App\Handler\Two:
        tags:
            - { name: 'app.handler', key: 'handler_two' }

    App\HandlerCollection:
        arguments: [!tagged_iterator { tag: 'app.handler', index_by: 'key' }]
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        <!-- 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="App\Handler\One">
            <tag name="app.handler" key="handler_one"/>
        </service>

        <service id="App\Handler\Two">
            <tag name="app.handler" key="handler_two"/>
        </service>

        <service id="App\HandlerCollection">
            <argument type="tagged_iterator" tag="app.handler" index-by="key"/>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Handler\One;
use App\Handler\Two;
use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;

return function (ContainerConfigurator $container): void {
    $services = $container->services();

    $services->set(One::class)
        ->tag('app.handler', ['key' => 'handler_one']);

    $services->set(Two::class)
        ->tag('app.handler', ['key' => 'handler_two']);

    $services->set(App\HandlerCollection::class)
        ->args([
            // 2nd argument is the index attribute name
            tagged_iterator('app.handler', 'key'),
        ])
    ;
};
    

У цьому прикладі опція index_by має значення key. Усі сервіси визначають цю опцію/атрибут, тож саме це значення буде використовуватися для індексації сервісів. Наприклад, щоб отримати сервіс App\Handler\Two:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // src/Handler/HandlerCollection.php
namespace App\Handler;

class HandlerCollection
{
    public function __construct(iterable $handlers)
    {
        $handlers = $handlers instanceof \Traversable ? iterator_to_array($handlers) : $handlers;

        // це значення визначено в опції сервіса `key`
        $handlerTwo = $handlers['handler_two'];
    }
}
    

Якщо якийсь сервіс не визначає опцію/атрибут, налаштований в index_by, Symfony застосовує цей резервний процес:

Якщо клас сервісу визначає статичний метод з назвою getDefault<CamelCase index_by value>Name (у цьому прикладі - getDefaultKeyName()), викличте його і використовуйте повернуте значення;
В іншому випадку поверніться до поведінки за замовчуванням і використовуйте ідентифікатор сервісу.

Опція `default_index_method`

Цей параметр визначає ім'я методу класу сервісу, який буде викликатися для отримання значення, яке використовується для індексації сервісів:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // src/HandlerCollection.php
namespace App;

use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;

class HandlerCollection
{
    public function __construct(
        #[TaggedIterator('app.handler', defaultIndexMethod: 'getIndex')]
        iterable $handlers
    ) {
    }
}
    

        1
2
3
4
5
6
        # config/services.yaml
services:
    # ...

    App\HandlerCollection:
        arguments: [!tagged_iterator { tag: 'app.handler', default_index_method: 'getIndex' }]
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- 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="App\HandlerCollection">
            <argument type="tagged_iterator"
                tag="app.handler"
                default-index-method="getIndex"
            />
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\HandlerCollection;
use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;

return function (ContainerConfigurator $container) {
    $services = $container->services();

    // ...

    $services->set(HandlerCollection::class)
        ->args([
            tagged_iterator('app.handler', null, 'getIndex'),
        ])
    ;
};
    

Якщо якийсь клас сервісу не визначає метод, заданий у default_index_method, Symfony повернеться до використання ідентифікатора сервісу як індексу всередині тегованих сервісів.

Поєднання опцій `index_by` та `default_index_method`

Ви можете поєднувати обидві опції в одній колекції тегованих сервісів. Symfony буде обробляти їх у наступному порядку:

Якщо сервіс визначає опцію/атрибут, сконфігурований у index_by, використовуйте його;
Якщо клас сервісу визначає метод, сконфігурований у default_index_method, використовуйте його;
В іншому випадку, поверніться до використання ідентифікатора сервісу як індексу всередині колекції тегованих сервісів.

Атрибут `#[AsTaggedItem]`

Можливо визначити як пріоритет, так і індекс тегованого обʼєкта, завдяки атрибуту #[AsTaggedItem]. Цей атрибут має бути використаний напряму у класі сервісу, який ви хочете сконфігурувати:

        1
2
3
4
5
6
7
8
9
10
        // src/Handler/One.php
namespace App\Handler;

use Symfony\Component\DependencyInjection\Attribute\AsTaggedItem;

#[AsTaggedItem(index: 'handler_one', priority: 10)]
class One
{
    // ...
}
    