Service Tags

In Symfony applications, it's common that some services must be processed in a special way by the framework or by third-party bundles. For example, you may create a class that adds some custom filters to Twig templates. Not every class can act as a Twig extension, so how can Twig know that, among all the classes of your application, this specific one is a Twig extension and must be registered as such?

Service tags solve this problem. Tags are labels that you add to service definitions to mark the purpose of each service. For example, thanks to service tags, Twig can collect all the services tagged with a tag called twig.extension to register them as Twig extensions.

This is how you would apply that tag to your service:

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

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 Symfony developers, this is all you need to know. If you want to go further and learn how to consume tagged services or 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 #[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
{
    // ...
}
    

When no tag name is specified, the fully qualified class name (FQCN) of the target is used:

        1
2
3
4
5
6
7
        // src/Security/CustomInterface.php

#[AutoconfigureTag] // equivalent to #[AutoconfigureTag(self::class)]
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.

You can achieve the same in configuration files with 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']
    # ...
    

Note

For more advanced needs, you can define the automatic tags from PHP code with the registerForAutoconfiguration() and registerAttributeForAutoconfiguration() methods. See how to autoconfigure tags from a compiler pass or kernel.

Adding Attributes to Tags

Tags can define additional attributes besides the tag name. These attributes store extra information about each tagged service. For example, the services tagged in the following example define a key attribute:

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

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

Tag attributes are used, for example, to index tagged services or to pass extra information to the compiler pass that processes the tag.

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 YAML format, you need to use this special syntax:

        1
2
3
4
5
6
7
8
        # config/services.yaml
services:
    App\Handler\One:
        tags:
            # this is a tag called 'app.handler'
            - { name: 'app.handler', key: 'handler_one' }
            # this is a tag called 'app.handler' with two attributes ('name' and 'key')
            - app.handler: { name: 'arbitrary-value', key: 'handler_one' }
    

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
        # config/services.yaml
services:
    # Compact syntax
    App\Handler\One:
        tags: ['app.handler']

    # Verbose syntax
    App\Handler\One:
        tags:
            - { name: 'app.handler' }
    

Computing Tag Attributes per Tagged Service

8.2

Support for computing tag attributes per tagged service was introduced in Symfony 8.2.

Autoconfigured tags attach the same attributes to every tagged service. To compute the attributes of each service instead, pass a callable in the form [SomeClass::class, 'someMethod'] as the tag attributes. When compiling the container, Symfony calls that static method on each concrete class implementing the interface:

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

use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag('app.handler', attributes: [self::class, 'getTagAttributes'])]
interface BatchHandlerInterface
{
    /**
     * @return array<string, mixed>
     */
    public static function getTagAttributes(): array;
}
    

Because the method is declared by the interface, PHP requires every class implementing it to define the method, and static analysis tools can detect mistakes in the callable. The method is called on the concrete class, so it can return attributes that depend on each class:

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

class RefundHandler implements BatchHandlerInterface
{
    public static function getTagAttributes(): array
    {
        return ['key' => 'refund'];
    }
}
    

The same callable can be used with the #[Autoconfigure] attribute and with the _instanceof option:

        1
2
3
4
5
6
        # config/services.yaml
services:
    _instanceof:
        App\Handler\BatchHandlerInterface:
            tags:
                - app.handler: [App\Handler\BatchHandlerInterface, getTagAttributes]
    

On PHP 8.5 and later, where closures are allowed in attributes, you can pass a closure receiving the concrete class-string instead of a static method:

        1
2
3
4
5
6
7
8
9
10
11
12
        // src/Handler/BatchHandlerInterface.php

// ...
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag('app.handler', attributes: static function (string $class): array {
    return ['key' => $class::getSupportedBatchAction()];
})]
interface BatchHandlerInterface
{
    public static function getSupportedBatchAction(): string;
}
    

Closures cannot be used in YAML files, so the static method callable is the only form available in that format.

Note

Tag attributes are computed when the container is compiled, once per concrete and instantiable class; abstract classes and interfaces are skipped. The callable must return an array; otherwise an exception is thrown.

Referencing Tagged Services

A common need is to inject all the services tagged with a specific tag into another service (e.g. to implement a chain, a registry or a collection of handlers). Symfony provides the tagged iterator shortcut for this, so you don't have to write a compiler pass for this common use case.

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
10
11
12
13
14
        // src/HandlerCollection.php
namespace App;

use Symfony\Component\DependencyInjection\Attribute\AutowireIterator;

class HandlerCollection
{
    public function __construct(
        // the attribute must be applied directly to the argument to autowire
        #[AutowireIterator('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:
        # inject all services tagged with app.handler as first argument
        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
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Handler\One;
use App\Handler\Two;
use App\HandlerCollection;

return App::config([
    'services' => [
        One::class => [
            'tags' => ['app.handler'],
        ],
        Two::class => [
            'tags' => ['app.handler'],
        ],
        HandlerCollection::class => [
            // inject all services tagged with app.handler as first argument
            'arguments' => [tagged_iterator('app.handler')],
        ],
    ],
]);
    

Note

Some IDEs will show an error when using #[AutowireIterator] 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.

Excluding Services from the Iterator

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\AutowireIterator;

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

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

        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;

use App\Handler\Three as HandlerThree;
use App\HandlerCollection;

return App::config([
    'services' => [
        // This is the service we want to exclude, even if the 'app.handler' tag is attached
        HandlerThree::class => [
            'tags' => ['app.handler'],
        ],
        HandlerCollection::class => [
            // inject all services tagged with app.handler as first argument
            'arguments' => [tagged_iterator('app.handler', exclude: [HandlerThree::class])],
        ],
    ],
]);
    

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\AutowireIterator;

class HandlerCollection
{
    public function __construct(
        #[AutowireIterator('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:
    # ...

    # 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'], exclude_self: false }
    

        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;

use App\Handler\Three;
use App\HandlerCollection;

return App::config([
    'services' => [
        // This is the service we want to exclude, even if the 'app.handler' tag is attached
        Three::class => [
            'tags' => ['app.handler'],
        ],
        HandlerCollection::class => [
            // inject all services tagged with app.handler as first argument
            'arguments' => [tagged_iterator('app.handler', exclude: [Three::class], excludeSelf: false)],
        ],
    ],
]);
    

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
6
7
8
9
10
        // src/Handler/One.php
namespace App\Handler;

use Symfony\Component\DependencyInjection\Attribute\AsTaggedItem;

#[AsTaggedItem(priority: 20)]
class One
{
    // ...
}
    

        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
14
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Handler\One;

return App::config([
    'services' => [
        One::class => [
            'tags' => [
                ['app.handler' => ['priority' => 20]],
            ],
        ],
    ],
]);
    

8.1

The getDefaultPriority() method is deprecated since Symfony 8.1. Use the #[AsTaggedItem] attribute instead.

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

8.1

The default_priority_method option is deprecated since Symfony 8.1. Use the #[AsTaggedItem] attribute instead.

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\AutowireIterator;

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

        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 }
    

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

use App\HandlerCollection;

return App::config([
    'services' => [
        HandlerCollection::class => [
            // inject all services tagged with app.handler as first argument
            'arguments' => [tagged_iterator('app.handler', defaultPriorityMethod: 'getPriority')],
        ],
    ],
]);
    

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\AutowireIterator;

class HandlerCollection
{
    public function __construct(
        #[AutowireIterator('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
22
23
24
25
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Handler\One;
use App\Handler\Two;
use App\HandlerCollection;

return App::config([
    'services' => [
        One::class => [
            'tags' => [
                ['app.handler' => ['key' => 'handler_one']],
            ],
        ],
        Two::class => [
            'tags' => [
                ['app.handler' => ['key' => 'handler_two']],
            ],
        ],
        HandlerCollection::class => [
            // 2nd argument is the index attribute name
            'arguments' => [tagged_iterator('app.handler', 'key')],
        ],
    ],
]);
    

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:

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;
Otherwise, fall back to the default behavior and use the service ID.

8.1

The getDefault<CamelCase index_by value>Name() method convention is deprecated since Symfony 8.1. Use the #[AsTaggedItem] attribute instead.

The `default_index_method` Option

8.1

The default_index_method option is deprecated since Symfony 8.1. Use the #[AsTaggedItem] attribute instead.

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\AutowireIterator;

class HandlerCollection
{
    public function __construct(
        #[AutowireIterator('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
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\HandlerCollection;

return App::config([
    'services' => [
        HandlerCollection::class => [
            'arguments' => [tagged_iterator('app.handler', defaultIndexMethod: 'getIndex')],
        ],
    ],
]);
    

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:

If the service defines the option/attribute configured in index_by, use it;
If the service class defines the method configured in default_index_method, use it;
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
{
    // ...
}
    

You can apply the #[AsTaggedItem] attribute multiple times to register the same service under different indexes:

        1
2
3
4
5
6
        #[AsTaggedItem(index: 'handler_one', priority: 5)]
#[AsTaggedItem(index: 'handler_two', priority: 20)]
class SomeService
{
    // ...
}
    

Tagging Non-Service Classes

Not all classes need to be registered as services. Entities, value objects, and DTOs, for example, should be discoverable at compile time but must not be instantiated by the container. Use resource tags to tag such classes while keeping them excluded from the service container.

The most direct option is the #[AutoconfigureResourceTag] attribute, which is repeatable and accepts an optional second argument with the tag attributes:

        1
2
3
4
5
6
7
8
9
10
11
        // src/Model/Invoice.php
namespace App\Model;

use Symfony\Component\DependencyInjection\Attribute\AutoconfigureResourceTag;

#[AutoconfigureResourceTag('app.report_item', ['type' => 'invoice'])]
#[AutoconfigureResourceTag('app.exportable')]
class Invoice
{
    // ...
}
    

The attribute also works on interfaces and base classes. In that case, every class that implements the interface or extends the base class receives the resource tag through autoconfiguration, the same way #[AutoconfigureTag] applies service tags:

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

use Symfony\Component\DependencyInjection\Attribute\AutoconfigureResourceTag;

#[AutoconfigureResourceTag('app.report_item')]
interface ReportItemInterface
{
    // ...
}
    

The same definitions can be declared per service in configuration files:

        1
2
3
4
5
6
        # config/services.yaml
services:
    App\Model\Invoice:
        resource_tags:
            - { name: 'app.report_item', type: 'invoice' }
            - 'app.exportable'
    

Tip

Resource tags can also be declared in the _defaults section to apply them to every service defined in the same file, using the same resource_tags option name in YAML and PHP.

When the resource tag setup requires custom logic, use the addResourceTag() method from PHP code:

        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/Attribute/AppModel.php
namespace App\Attribute;

#[\Attribute(\Attribute::TARGET_CLASS)]
class AppModel
{
}

// src/Kernel.php
use App\Attribute\AppModel;
use Symfony\Component\DependencyInjection\ChildDefinition;

class Kernel extends BaseKernel
{
    // ...

    protected function build(ContainerBuilder $container): void
    {
        // classes annotated with ``#[AppModel]`` will be tagged with ``app.model`` and
        // automatically excluded from the container (they won't be instantiated as services)
        $container->registerAttributeForAutoconfiguration(
            AppModel::class,
            static function (ChildDefinition $definition): void {
                $definition->addResourceTag('app.model');
            }
        );
    }
}
    

You can then retrieve these classes in a compiler pass using findTaggedResourceIds():

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        // src/DependencyInjection/Compiler/ModelDiscoveryPass.php
namespace App\DependencyInjection\Compiler;

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

class ModelDiscoveryPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        $classes = [];

        foreach ($container->findTaggedResourceIds('app.model') as $id => $tags) {
            $classes[] = $container->getDefinition($id)->getClass();
        }

        $container->setParameter('app.model_classes', $classes);
    }
}
    

Creating Custom Tags and Processing Them with Compiler Passes

Tags on their own don't actually alter the functionality of your services in any way. You can create and apply any custom tag (e.g. app.report_generator) to your services and nothing will happen. Tags "mean" something when some code asks the container for the list of services tagged with them.

For the most common use case (injecting all the tagged services into another service) use the tagged iterators explained earlier in this article. When you need full control (e.g. calling a specific method on a collecting service for each tagged service, or using tag attributes with custom logic), write a compiler pass. Compiler passes ask the container for the tagged services with the findTaggedServiceIds() method and modify the service definitions before the container is compiled.

Read how to process tagged services in a compiler pass for the full explanation and examples.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version