How to Work with Service Tags

Service tags are a way to tell Symfony or other third-party bundles that your service should be registered in some special way. Take the following example:

サービスタグは、サービスを特別な方法で登録する必要があることを Symfony または他のサードパーティのバンドルに伝える方法です。次の例を見てください。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
 
# config/services.yaml
services:
    App\Twig\AppExtension:
        tags: ['twig.extension']

Services tagged with the twig.extension tag are collected during the initialization of TwigBundle and added to Twig as extensions.

twig.extension タグでタグ付けされたサービスは、TwigBundle の初期化中に収集され、拡張機能として Twig に追加されます。

Other tags are used to integrate your services into other systems. For a list of all the tags available in the core Symfony Framework, check out Built-in Symfony Service Tags. Each of these has a different effect on your service and many tags require additional arguments (beyond the name parameter).

他のタグは、サービスを他のシステムに統合するために使用されます。コア Symfony フレームワークで利用可能なすべてのタグのリストについては、組み込みの Symfony サービス タグを確認してください。これらはそれぞれサービスに異なる影響を与え、多くのタグには追加の引数が必要です (name パラメーター以外)。

For most users, this is all you need to know. If you want to go further and learn how to create your own custom tags, keep reading.

ほとんどのユーザーにとって、知っておく必要があるのはこれだけです。さらに進んで、独自のカスタム タグを作成する方法を学びたい場合は、読み続けてください。

Autoconfiguring Tags

If you enable autoconfigure, then some tags are automatically applied for you. That's true for the twig.extension tag: the container sees that your class extends AbstractExtension (or more accurately, that it implements ExtensionInterface) and adds the tag for you.

自動構成を有効にすると、一部のタグが自動的に適用されます。これは twig.extension タグにも当てはまります。コンテナは、クラスが AbstractExtension を拡張していること (より正確には、ExtensionInterface を実装していること) を認識し、タグを追加します。

If you want to apply tags automatically for your own services, use the _instanceof option:

独自のサービスにタグを自動的に適用する場合は、_instanceof オプションを使用します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
 
# config/services.yaml
services:
    # this config only applies to the services created by this file
    _instanceof:
        # services whose classes are instances of CustomInterface will be tagged automatically
        App\Security\CustomInterface:
            tags: ['app.custom_tag']
    # ...

For more advanced needs, you can define the automatic tags using the registerForAutoconfiguration() method.

より高度なニーズについては、registerForAutoconfiguration() メソッドを使用して自動タグを定義できます。

In a Symfony application, call this method in your kernel class:

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')
        ;
    }
}

In a Symfony bundle, call this method in the load() method of the bundle extension class:

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')
        ;
    }
}

Creating custom Tags

Tags on their own don't actually alter the functionality of your services in any way. But if you choose to, you can ask a container builder for a list of all services that were tagged with some specific tag. This is useful in compiler passes where you can find these services and use or modify them in some specific way.

タグ自体が実際にサービスの機能を変更することはありません。ただし、必要に応じて、特定のタグでタグ付けされたすべてのサービスのリストをコンテナー ビルダーに依頼できます。これは、これらのサービスを見つけて特定の方法で使用または変更できる便利なコンパイラ パスです。

For example, if you are using the Symfony Mailer component you might want to implement a "transport chain", which is a collection of classes implementing \MailerTransport. Using the chain, you'll want Mailer to try several ways of transporting the message until one succeeds.

たとえば、Symfony Mailer コンポーネントを使用している場合、\MailerTransport を実装するクラスのコレクションである「トランスポート チェーン」を実装したい場合があります。チェーンを使用すると、成功するまで、Mailer にメッセージを転送するいくつかの方法を試してもらいます。

To begin with, define the TransportChain class:

まず、TransportChain クラスを定義します。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
// src/Mail/TransportChain.php
namespace App\Mail;

class TransportChain
{
    private $transports;

    public function __construct()
    {
        $this->transports = [];
    }

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

Then, define the chain as a service:

次に、チェーンをサービスとして定義します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
 
# config/services.yaml
services:
    App\Mail\TransportChain: ~

Define Services with a Custom Tag

Now you might want several of the \MailerTransport classes to be instantiated and added to the chain automatically using the addTransport() method. For example, you may add the following transports as services:

addTransport() メソッドを使用して、\MailerTransport クラスのいくつかをインスタンス化し、チェーンに自動的に追加することができます。たとえば、次のトランスポートをサービスとして追加できます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
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']

Notice that each service was given a tag named app.mail_transport. This is the custom tag that you'll use in your compiler pass. The compiler pass is what makes this tag "mean" something.

各サービスには、app.mail_transport という名前のタグが付けられていることに注意してください。これは、コンパイラ パスで使用するカスタム タグです。コンパイラ パスは、このタグを「意味」のあるものにします。

Create a Compiler Pass

You can now use a compiler pass to ask the container for any services with the app.mail_transport tag:

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
    {
        // always first check if the primary service is defined
        if (!$container->has(TransportChain::class)) {
            return;
        }

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

        // find all service IDs with the app.mail_transport tag
        $taggedServices = $container->findTaggedServiceIds('app.mail_transport');

        foreach ($taggedServices as $id => $tags) {
            // add the transport service to the TransportChain service
            $definition->addMethodCall('addTransport', [new Reference($id)]);
        }
    }
}

Register the Pass with the Container

In order to run the compiler pass when the container is compiled, you have to add the compiler pass to the container in a bundle extension or from your kernel:

コンテナのコンパイル時にコンパイラ パスを実行するには、バンドル エクステンションまたはカーネルからコンテナにコンパイラ パスを追加する必要があります。
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

ヒント

When implementing the CompilerPassInterface in a service extension, you do not need to register it. See the components documentation for more information.

サービス拡張で CompilerPassInterface を実装する場合は、登録する必要はありません。詳細については、コンポーネントのドキュメントを参照してください。

Adding Additional Attributes on Tags

Sometimes you need additional information about each service that's tagged with your tag. For example, you might want to add an alias to each member of the transport chain.

タグでタグ付けされた各サービスに関する追加情報が必要になる場合があります。たとえば、トランスポート チェーンの各メンバーにエイリアスを追加できます。

To begin with, change the TransportChain class:

まず、TransportChain クラスを変更します。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
class TransportChain
{
    private $transports;

    public function __construct()
    {
        $this->transports = [];
    }

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

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

        return null;
    }
}

As you can see, when addTransport() is called, it takes not only a MailerTransport object, but also a string alias for that transport. So, how can you allow each tagged transport service to also supply an alias?

ご覧のとおり、addTransport() が呼び出されると、MailerTransport オブジェクトだけでなく、そのトランスポートの文字列エイリアスも取得します。では、タグ付けされた各トランスポート サービスがエイリアスを提供できるようにするにはどうすればよいでしょうか。

To answer this, change the service declaration:

これに答えるには、サービス宣言を変更します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
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' }

Tip

ヒント

In YAML format, you may provide the tag as a simple string as long as you don't need to specify additional attributes. The following definitions are equivalent.

YAML 形式では、追加の属性を指定する必要がない限り、タグを単純な文字列として指定できます。以下の定義は同等です。
1
2
3
4
5
6
7
8
9
10
11
12
 
# config/services.yaml
services:
    # Compact syntax
    MailerSendmailTransport:
        class: \MailerSendmailTransport
        tags: ['app.mail_transport']

    # Verbose syntax
    MailerSendmailTransport:
        class: \MailerSendmailTransport
        tags:
            - { name: 'app.mail_transport' }

Notice that you've added a generic alias key to the tag. To actually use this, update the compiler:

タグに一般的なエイリアス キーを追加したことに注意してください。これを実際に使用するには、コンパイラを更新します。
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) {

            // a service could have the same tag twice
            foreach ($tags as $attributes) {
                $definition->addMethodCall('addTransport', [
                    new Reference($id),
                    $attributes['alias'],
                ]);
            }
        }
    }
}

The double loop may be confusing. This is because a service can have more than one tag. You tag a service twice or more with the app.mail_transport tag. The second foreach loop iterates over the app.mail_transport tags set for the current service and gives you the attributes.

二重ループは紛らわしいかもしれません。これは、サービスが複数のタグを持つことができるためです。 app.mail_transporttag を使用して、サービスに 2 回以上タグを付けます。 2 番目の foreach ループは、現在のサービスに設定された app.mail_transporttags を反復処理し、属性を提供します。

Reference Tagged Services

Symfony provides a shortcut to inject all services tagged with a specific tag, which is a common need in some applications, so you don't have to write a compiler pass just for that.

Symfony は、特定のタグでタグ付けされたすべてのサービスを注入するためのショートカットを提供します。これは、一部のアプリケーションで一般的に必要とされるため、そのためだけにコンパイラ パスを記述する必要はありません。

In the following example, all services tagged with app.handler are passed as first constructor argument to the App\HandlerCollection service:

次の例では、app.handler でタグ付けされたすべてのサービスが、firstconstructor 引数として App\HandlerCollection サービスに渡されます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
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:
        # inject all services tagged with app.handler as first argument
        arguments:
            - !tagged_iterator app.handler

After compilation the HandlerCollection service is able to iterate over your application handlers:

コンパイル後、HandlerCollection サービスはアプリケーション ハンドラを反復処理できます。
1
2
3
4
5
6
7
8
9
 
// src/HandlerCollection.php
namespace App;

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

If for some reason you need to exclude one or more services when using a tagged iterator, add the exclude option:

何らかの理由で、tagediterator を使用するときに 1 つ以上のサービスを除外する必要がある場合は、除外オプションを追加します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
 
# config/services.yaml
services:
    # ...

    # This is the service we want to exclude, even if the 'app.handler' tag is attached
    App\Handler\Three:
        tags: ['app.handler']

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

6.1

6.1

The exclude option was introduced in Symfony 6.1.

exclude オプションは Symfony 6.1 で導入されました。

See also

こちらもご覧ください

See also tagged locator services

タグ付きロケーター サービスも参照

Tagged Services with Priority

The tagged services can be prioritized using the priority attribute. The priority is a positive or negative integer that defaults to 0. The higher the number, the earlier the tagged service will be located in the collection:

タグ付けされたサービスは、priority 属性を使用して優先順位を付けることができます。優先度は正または負の整数で、デフォルトは 0 です。数値が大きいほど、タグ付けされたサービスがコレクション内でより早く検索されます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/services.yaml
services:
    App\Handler\One:
        tags:
            - { name: 'app.handler', priority: 20 }

Another option, which is particularly useful when using autoconfiguring tags, is to implement the static getDefaultPriority() method on the service itself:

自動構成タグを使用する場合に特に役立つ別のオプションは、静的な 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;
    }
}

If you want to have another method defining the priority (e.g. getPriority() rather than getDefaultPriority()), you can define it in the configuration of the collecting service:

優先度を定義する別のメソッド (getDefaultPriority() ではなく getPriority() など) が必要な場合は、収集サービスの構成で定義できます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
 
# config/services.yaml
services:
    App\HandlerCollection:
        # inject all services tagged with app.handler as first argument
        arguments:
            - !tagged_iterator { tag: app.handler, default_priority_method: getPriority }

Tagged Services with Index

If you want to retrieve a specific service within the injected collection you can use the index_by and default_index_method options of the argument in combination with !tagged_iterator.

挿入されたコレクション内の特定のサービスを取得する場合は、引数の index_by および default_index_method オプションを !tagged_iterator と組み合わせて使用​​できます。

Using the previous example, this service configuration creates a collection indexed by the key attribute:

前の例を使用して、このサービス構成は、キー属性によってインデックス付けされたコレクションを作成します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
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' }]

After compilation the HandlerCollection is able to iterate over your application handlers. To retrieve a specific service from the iterator, call the iterator_to_array() function and then use the key attribute to get the array element. For example, to retrieve the handler_two handler:

コンパイル後、HandlerCollection はアプリケーション ハンドラを反復処理できます。イテレータから特定のサービスを取得するには、iterator_to_array() 関数を呼び出してから、key 属性を使用して配列要素を取得します。たとえば、handler_two ハンドラーを取得するには、次のようにします。
1
2
3
4
5
6
7
8
9
10
11
12
 
// src/Handler/HandlerCollection.php
namespace App\Handler;

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

        $handlerTwo = $handlers['handler_two'];
    }
}

Tip

ヒント

Just like the priority, you can also implement a static getDefaultIndexName() method in the handlers and omit the index attribute (key):

優先度と同様に、ハンドラーに staticgetDefaultIndexName() メソッドを実装して、index 属性 (キー) を省略することもできます。
1
2
3
4
5
6
7
8
9
10
11
 
// src/Handler/One.php
namespace App\Handler;

class One
{
    // ...
    public static function getDefaultIndexName(): string
    {
        return 'handler_one';
    }
}

You also can define the name of the static method to implement on each service with the default_index_method attribute on the tagged argument:

タグ付き引数の default_index_method 属性を使用して、各サービスに実装する静的メソッドの名前を定義することもできます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
 
# config/services.yaml
services:
    # ...

    App\HandlerCollection:
        # use getIndex() instead of getDefaultIndexName()
        arguments: [!tagged_iterator { tag: 'app.handler', default_index_method: 'getIndex' }]