How to Work with Service Tags

Warning: You are browsing the documentation for Symfony 6.3, which is no longer maintained.

Read the updated version of this page for Symfony 7.1 (the current stable version).

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:

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.

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).

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.

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

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']
    # ...

Caution

If you're using PHP configuration, you need to call instanceof before any service registration to make sure tags are correctly applied.

It is also possible to use the #[AutoconfigureTag] attribute directly on the base class or interface:

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

If you need more capabilities to autoconfigure instances of your base class like their laziness, their bindings or their calls for example, you may rely on the Autoconfigure attribute.

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

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

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:

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

Autoconfiguration registering is not limited to interfaces. It is possible to use PHP attributes to autoconfigure services by using the registerAttributeForAutoconfiguration() method:

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 {
            // Apply the 'app.sensitive_element' tag to all classes with SensitiveElement
            // attribute, and attach the token value to the tag
            $definition->addTag('app.sensitive_element', ['token' => $attribute->getToken()]);
        });
    }
}

You can also make attributes usable on methods. To do so, update the previous example and add 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
{
    // ...
}

Then, update the registerAttributeForAutoconfiguration() call to support 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,
            // update the union type to support multiple types of reflection
            // you can also use the "\Reflector" interface
            \ReflectionClass|\ReflectionMethod $reflector): void {
                if ($reflection instanceof \ReflectionMethod) {
                    // ...
                }
            }
        );
    }
}

Tip

You can also define an attribute to be usable on properties and parameters with Attribute::TARGET_PROPERTY and Attribute::TARGET_PARAMETER; then support ReflectionProperty and ReflectionParameter in your registerAttributeForAutoconfiguration() callable.

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.

To begin with, define the TransportChain class:

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

Then, define the chain as a service:

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:

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.

Create a Compiler Pass

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

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.

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:

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

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?

To answer this, change the service declaration:

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']}

6.2

Support for attributes as array was introduced in Symfony 6.2.

Tip

The name attribute is used by default to define the name of the tag. If you want to add a name attribute to some tag in XML or YAML formats, you need to use this special syntax:

1
2
3
4
5
6
7
8
9
# config/services.yaml
services:
    MailerSmtpTransport:
        arguments: ['%mailer_host%']
        tags:
            # this is a tag called 'app.mail_transport'
            - { name: 'app.mail_transport', alias: 'smtp' }
            # this is a tag called 'app.mail_transport' with two attributes ('name' and 'alias')
            - app.mail_transport: { name: 'arbitrary-value', alias: 'smtp' }

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.

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.

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.

Consider the following HandlerCollection class where you want to inject all services tagged with app.handler into its constructor argument:

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

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

Symfony allows you to inject the services using YAML/XML/PHP configuration or directly via PHP attributes:

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

use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;

class HandlerCollection
{
    public function __construct(
        // the attribute must be applied directly to the argument to autowire
        #[TaggedIterator('app.handler')]
        iterable $handlers
    ) {
    }
}

Note

Some IDEs will show an error when using #[TaggedIterator] together with the PHP constructor promotion: "Attribute cannot be applied to a property because it does not contain the 'Attribute::TARGET_PROPERTY' flag". The reason is that those constructor arguments are both parameters and class properties. You can safely ignore this error message.

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

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
    ) {
    }
}

In the case the referencing service is itself tagged with the tag being used in the tagged iterator, it is automatically excluded from the injected iterable. This behavior can be disabled by setting the exclude_self option to 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
    ) {
    }
}

6.1

The exclude option was introduced in Symfony 6.1.

6.3

The exclude_self option and the automatic exclusion of the referencing service in the injected iterable were introduced in Symfony 6.3.

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:

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:

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:

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
    ) {
    }
}

Tagged Services with Index

By default, tagged services are indexed using their service IDs. You can change this behavior with two options of the tagged iterator (index_by and default_index_method) which can be used independently or combined.

The index_by / indexAttribute Option

This option defines the name of the option/attribute that stores the value used to index the services:

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
    ) {
    }
}

In this example, the index_by option is key. All services define that option/attribute, so that will be the value used to index the services. For example, to get the App\Handler\Two service:

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;

        // this value is defined in the `key` option of the service
        $handlerTwo = $handlers['handler_two'];
    }
}

If some service doesn't define the option/attribute configured in index_by, Symfony applies this fallback process:

  1. If the service class defines a static method called getDefault<CamelCase index_by value>Name (in this example, getDefaultKeyName()), call it and use the returned value;
  2. Otherwise, fall back to the default behavior and use the service ID.

The default_index_method Option

This option defines the name of the service class method that will be called to get the value used to index the services:

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
    ) {
    }
}

If some service class doesn't define the method configured in default_index_method, Symfony will fall back to using the service ID as its index inside the tagged services.

Combining the index_by and default_index_method Options

You can combine both options in the same collection of tagged services. Symfony will process them in the following order:

  1. If the service defines the option/attribute configured in index_by, use it;
  2. If the service class defines the method configured in default_index_method, use it;
  3. Otherwise, fall back to using the service ID as its index inside the tagged services collection.

The #[AsTaggedItem] attribute

It is possible to define both the priority and the index of a tagged item thanks to the #[AsTaggedItem] attribute. This attribute must be used directly on the class of the service you want to configure:

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
{
    // ...
}
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version