Built-in Symfony Service Tags

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

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

Service tags are the mechanism used by the DependencyInjection component to flag services that require special processing, like console commands or Twig extensions.

These are the most common tags provided by Symfony components, but in your application there could be more tags available provided by third-party bundles:

Tag Name Usage
assetic.asset Register an asset to the current asset manager
assetic.factory_worker Add a factory worker
assetic.filter Register a filter
assetic.formula_loader Add a formula loader to the current asset manager
assetic.formula_resource Adds a resource to the current asset manager
assetic.templating.php Remove this service if PHP templating is disabled
assetic.templating.twig Remove this service if Twig templating is disabled
auto_alias Define aliases based on the value of container parameters
console.command Add a command
data_collector Create a class that collects custom data for the profiler
doctrine.event_listener Add a Doctrine event listener
doctrine.event_subscriber Add a Doctrine event subscriber
form.type Create a custom form field type
form.type_extension Create a custom "form extension"
form.type_guesser Add your own logic for "form type guessing"
kernel.cache_clearer Register your service to be called during the cache clearing process
kernel.cache_warmer Register your service to be called during the cache warming process
kernel.event_listener Listen to different events/hooks in Symfony
kernel.event_subscriber To subscribe to a set of different events/hooks in Symfony
kernel.fragment_renderer Add new HTTP content rendering strategies
monolog.logger Logging with a custom logging channel
monolog.processor Add a custom processor for logging
routing.loader Register a custom service that loads routes
routing.expression_language_provider Register a provider for expression language functions in routing
security.expression_language_provider Register a provider for expression language functions in security
security.voter Add a custom voter to Symfony's authorization logic
security.remember_me_aware To allow remember me authentication
serializer.encoder Register a new encoder in the serializer service
serializer.normalizer Register a new normalizer in the serializer service
swiftmailer.default.plugin Register a custom SwiftMailer Plugin
templating.helper Make your service available in PHP templates
translation.loader Register a custom service that loads translations
translation.extractor Register a custom service that extracts translation messages from a file
translation.dumper Register a custom service that dumps translation messages
twig.extension Register a custom Twig Extension
twig.loader Register a custom service that loads Twig templates
validator.constraint_validator Create your own custom validation constraint
validator.initializer Register a service that initializes objects before validation

assetic.asset

Purpose: Register an asset with the current asset manager

assetic.factory_worker

Purpose: Add a factory worker

A Factory worker is a class implementing Assetic\Factory\Worker\WorkerInterface. Its process($asset) method is called for each asset after asset creation. You can modify an asset or even return a new one.

In order to add a new worker, first create a class:

1
2
3
4
5
6
7
8
9
10
11
use Assetic\Asset\AssetInterface;
use Assetic\Factory\Worker\WorkerInterface;

class MyWorker implements WorkerInterface
{
    public function process(AssetInterface $asset)
    {
        // ... change $asset or return a new one
    }

}

And then register it as a tagged service:

1
2
3
4
5
services:
    app.custom_assetic_worker:
        class: AppBundle\Assetic\CustomWorker
        tags:
            - { name: assetic.factory_worker }

assetic.filter

Purpose: Register a filter

AsseticBundle uses this tag to register common filters. You can also use this tag to register your own filters.

First, you need to create a filter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
use Assetic\Asset\AssetInterface;
use Assetic\Filter\FilterInterface;

class MyFilter implements FilterInterface
{
    public function filterLoad(AssetInterface $asset)
    {
        $asset->setContent('alert("yo");' . $asset->getContent());
    }

    public function filterDump(AssetInterface $asset)
    {
        // ...
    }
}

Second, define a service:

1
2
3
4
5
services:
    app.custom_assetic_filter:
        class: AppBundle\Assetic\CustomFilter
        tags:
            - { name: assetic.filter, alias: my_filter }

Finally, apply the filter:

1
2
3
4
5
6
{% javascripts
    '@AcmeBaseBundle/Resources/public/js/global.js'
    filter='my_filter'
%}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

You can also apply your filter via the assetic.filters.my_filter.apply_to config option as it's described here: How to Apply an Assetic Filter to a specific File Extension. In order to do that, you must define your filter service in a separate xml config file and point to this file's path via the assetic.filters.my_filter.resource configuration key.

assetic.formula_loader

Purpose: Add a formula loader to the current asset manager

A Formula loader is a class implementing Assetic\\Factory\Loader\\FormulaLoaderInterface interface. This class is responsible for loading assets from a particular kind of resources (for instance, twig template). Assetic ships loaders for PHP and Twig templates.

An alias attribute defines the name of the loader.

assetic.formula_resource

Purpose: Adds a resource to the current asset manager

A resource is something formulae can be loaded from. For instance, Twig templates are resources.

assetic.templating.php

Purpose: Remove this service if PHP templating is disabled

The tagged service will be removed from the container if the framework.templating.engines config section does not contain php.

assetic.templating.twig

Purpose: Remove this service if Twig templating is disabled

The tagged service will be removed from the container if framework.templating.engines config section does not contain twig.

auto_alias

2.7

The auto_alias tag was introduced in Symfony 2.7.

Purpose: Define aliases based on the value of container parameters

Consider the following configuration that defines three different but related services:

1
2
3
4
5
6
7
8
9
10
services:
    app.mysql_lock:
        class: AppBundle\Lock\MysqlLock
        public: false
    app.postgresql_lock:
        class: AppBundle\Lock\PostgresqlLock
        public: false
    app.sqlite_lock:
        class: AppBundle\Lock\SqliteLock
        public: false

Instead of dealing with these three services, your application needs a generic app.lock service that will be an alias to one of these services, depending on some configuration. Thanks to the auto_alias option, you can automatically create that alias based on the value of a configuration parameter.

Considering that a configuration parameter called database_type exists. Then, the generic app.lock service can be defined as follows:

1
2
3
4
5
6
7
8
9
10
services:
    app.mysql_lock:
        # ...
    app.postgresql_lock:
        # ...
    app.sqlite_lock:
        # ...
    app.lock:
        tags:
            - { name: auto_alias, format: "app.%database_type%_lock" }

The format option defines the expression used to construct the name of the service to alias. This expression can use any container parameter (as usual, wrapping their names with % characters).

Note

When using the auto_alias tag, it's not mandatory to define the aliased services as private. However, doing that (like in the above example) makes sense most of the times to prevent accessing those services directly instead of using the generic service alias.

Note

You need to manually add the Symfony\Component\DependencyInjection\Compiler\AutoAliasServicePass compiler pass to the container for this feature to work.

console.command

Purpose: Add a command to the application

For details on registering your own commands in the service container, read How to Define Commands as Services.

data_collector

Purpose: Create a class that collects custom data for the profiler

For details on creating your own custom data collection, read the How to Create a custom Data Collector article.

doctrine.event_listener

Purpose: Add a Doctrine event listener

For details on creating Doctrine event listeners, read the Doctrine Event Listeners and Subscribers article.

doctrine.event_subscriber

Purpose: Add a Doctrine event subscriber

For details on creating Doctrine event subscribers, read the Doctrine Event Listeners and Subscribers article.

form.type

Purpose: Create a custom form field type

For details on creating your own custom form type, read the How to Create a Custom Form Field Type article.

form.type_extension

Purpose: Create a custom "form extension"

For details on creating Form type extensions, read the How to Create a Form Type Extension article.

form.type_guesser

Purpose: Add your own logic for "form type guessing"

This tag allows you to add your own logic to the form guessing process. By default, form guessing is done by "guessers" based on the validation metadata and Doctrine metadata (if you're using Doctrine) or Propel metadata (if you're using Propel).

See also

For information on how to create your own type guesser, see Creating a custom Type Guesser.

kernel.cache_clearer

Purpose: Register your service to be called during the cache clearing process

Cache clearing occurs whenever you call cache:clear command. If your bundle caches files, you should add custom cache clearer for clearing those files during the cache clearing process.

In order to register your custom cache clearer, first you must create a service class:

1
2
3
4
5
6
7
8
9
10
11
12
13
// src/AppBundle/Cache/MyClearer.php
namespace AppBundle\Cache;

use Symfony\Component\HttpKernel\CacheClearer\CacheClearerInterface;

class MyClearer implements CacheClearerInterface
{
    public function clear($cacheDirectory)
    {
        // clear your cache
    }

}

Then register this class and tag it with kernel.cache_clearer:

1
2
3
4
5
services:
    my_cache_clearer:
        class: AppBundle\Cache\MyClearer
        tags:
            - { name: kernel.cache_clearer }

kernel.cache_warmer

Purpose: Register your service to be called during the cache warming process

Cache warming occurs whenever you run the cache:warmup or cache:clear command (unless you pass --no-warmup to cache:clear). It is also run when handling the request, if it wasn't done by one of the commands yet. The purpose is to initialize any cache that will be needed by the application and prevent the first user from any significant "cache hit" where the cache is generated dynamically.

To register your own cache warmer, first create a service that implements the CacheWarmerInterface interface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// src/Acme/MainBundle/Cache/MyCustomWarmer.php
namespace AppBundle\Cache;

use Symfony\Component\HttpKernel\CacheWarmer\CacheWarmerInterface;

class MyCustomWarmer implements CacheWarmerInterface
{
    public function warmUp($cacheDirectory)
    {
        // ... do some sort of operations to "warm" your cache
    }

    public function isOptional()
    {
        return true;
    }
}

The isOptional() method should return true if it's possible to use the application without calling this cache warmer. In Symfony, optional warmers are always executed by default (you can change this by using the --no-optional-warmers option when executing the command).

To register your warmer with Symfony, give it the kernel.cache_warmer tag:

1
2
3
4
5
services:
    app.warmer.my_custom_warmer:
        class: AppBundle\Cache\MyCustomWarmer
        tags:
            - { name: kernel.cache_warmer, priority: 0 }

Note

The priority is optional and its value is a positive or negative integer that defaults to 0. The higher the number, the earlier that warmers are executed.

Caution

If your cache warmer fails its execution because of any exception, Symfony won't try to execute it again for the next requests. Therefore, your application and/or bundles should be prepared for when the contents generated by the cache warmer are not available.

Core Cache Warmers

Cache Warmer Class Name Priority
TemplatePathsCacheWarmer 20
RouterCacheWarmer 0
TemplateCacheCacheWarmer 0

kernel.event_listener

Purpose: To listen to different events/hooks in Symfony

During the execution of a Symfony application, different events are triggered and you can also dispatch custom events. This tag allows you to hook your own classes into any of those events.

For a full example of this listener, read the Events and Event Listeners article.

Core Event Listener Reference

For the reference of Event Listeners associated with each kernel event, see the Symfony Events Reference.

kernel.event_subscriber

Purpose: To subscribe to a set of different events/hooks in Symfony

To enable a custom subscriber, add it as a regular service in one of your configuration and tag it with kernel.event_subscriber:

1
2
3
4
5
services:
    app.custom_subscriber:
        class: AppBundle\EventListener\CustomSubscriber
        tags:
            - { name: kernel.event_subscriber }

Note

Your service must implement the EventSubscriberInterface interface.

Note

If your service is created by a factory, you MUST correctly set the class parameter for this tag to work correctly.

kernel.fragment_renderer

Purpose: Add a new HTTP content rendering strategy

To add a new rendering strategy - in addition to the core strategies like EsiFragmentRenderer - create a class that implements FragmentRendererInterface, register it as a service, then tag it with kernel.fragment_renderer.

monolog.logger

Purpose: To use a custom logging channel with Monolog

Monolog allows you to share its handlers between several logging channels. The logger service uses the channel app but you can change the channel when injecting the logger in a service.

1
2
3
4
5
6
services:
    app.custom_logger:
        class: AppBundle\Log\CustomLogger
        arguments: ['@logger']
        tags:
            - { name: monolog.logger, channel: acme }

Tip

If you use MonologBundle 2.4 or higher, you can configure custom channels in the configuration and retrieve the corresponding logger service from the service container directly (see How to Log Messages to different Files).

monolog.processor

Purpose: Add a custom processor for logging

Monolog allows you to add processors in the logger or in the handlers to add extra data in the records. A processor receives the record as an argument and must return it after adding some extra data in the extra attribute of the record.

The built-in IntrospectionProcessor can be used to add the file, the line, the class and the method where the logger was triggered.

You can add a processor globally:

1
2
3
4
5
services:
    my_service:
        class: Monolog\Processor\IntrospectionProcessor
        tags:
            - { name: monolog.processor }

Tip

If your service is not a callable (using __invoke()) you can add the method attribute in the tag to use a specific method.

You can add also a processor for a specific handler by using the handler attribute:

1
2
3
4
5
services:
    my_service:
        class: Monolog\Processor\IntrospectionProcessor
        tags:
            - { name: monolog.processor, handler: firephp }

You can also add a processor for a specific logging channel by using the channel attribute. This will register the processor only for the security logging channel used in the Security component:

1
2
3
4
5
services:
    my_service:
        class: Monolog\Processor\IntrospectionProcessor
        tags:
            - { name: monolog.processor, channel: security }

Note

You cannot use both the handler and channel attributes for the same tag as handlers are shared between all channels.

routing.loader

Purpose: Register a custom service that loads routes

To enable a custom routing loader, add it as a regular service in one of your configuration and tag it with routing.loader:

1
2
3
4
5
services:
    app.custom_routing_loader:
        class: AppBundle\Routing\CustomLoader
        tags:
            - { name: routing.loader }

For more information, see How to Create a custom Route Loader.

routing.expression_language_provider

Purpose: Register a provider for expression language functions in routing

This tag is used to automatically register expression function providers for the routing expression component. Using these providers, you can add custom functions to the routing expression language.

security.expression_language_provider

Purpose: Register a provider for expression language functions in security

This tag is used to automatically register expression function providers for the security expression component. Using these providers, you can add custom functions to the security expression language.

security.remember_me_aware

Purpose: To allow remember me authentication

This tag is used internally to allow remember-me authentication to work. If you have a custom authentication method where a user can be remember-me authenticated, then you may need to use this tag.

If your custom authentication factory extends AbstractFactory and your custom authentication listener extends AbstractAuthenticationListener, then your custom authentication listener will automatically have this tag applied and it will function automatically.

security.voter

Purpose: To add a custom voter to Symfony's authorization logic

When you call isGranted() on Symfony's authorization checker, a system of "voters" is used behind the scenes to determine if the user should have access. The security.voter tag allows you to add your own custom voter to that system.

For more information, read the How to Use Voters to Check User Permissions article.

serializer.encoder

Purpose: Register a new encoder in the serializer service

The class that's tagged should implement the EncoderInterface and DecoderInterface.

For more details, see How to Use the Serializer.

serializer.normalizer

Purpose: Register a new normalizer in the Serializer service

The class that's tagged should implement the NormalizerInterface and DenormalizerInterface.

For more details, see How to Use the Serializer.

The priorities of the default normalizers can be found in the registerSerializerConfiguration() method.

swiftmailer.default.plugin

Purpose: Register a custom SwiftMailer Plugin

If you're using a custom SwiftMailer plugin (or want to create one), you can register it with SwiftMailer by creating a service for your plugin and tagging it with swiftmailer.default.plugin (it has no options).

Note

default in this tag is the name of the mailer. If you have multiple mailers configured or have changed the default mailer name for some reason, you should change it to the name of your mailer in order to use this tag.

A SwiftMailer plugin must implement the Swift_Events_EventListener interface. For more information on plugins, see SwiftMailer's Plugin Documentation.

Several SwiftMailer plugins are core to Symfony and can be activated via different configuration. For details, see Mailer Configuration Reference (SwiftmailerBundle).

templating.helper

Purpose: Make your service available in PHP templates

To enable a custom template helper, add it as a regular service in one of your configuration, tag it with templating.helper and define an alias attribute (the helper will be accessible via this alias in the templates):

1
2
3
4
5
services:
    app.templating_helper:
        class: AppBundle\Templating\AppHelper
        tags:
            - { name: templating.helper, alias: alias_name }

translation.loader

Purpose: To register a custom service that loads translations

By default, translations are loaded from the filesystem in a variety of different formats (YAML, XLIFF, PHP, etc).

See also

Learn how to load custom formats in the components section.

Now, register your loader as a service and tag it with translation.loader:

1
2
3
4
5
services:
    app.translation.my_custom_loader:
        class: AppBundle\Translation\MyCustomLoader
        tags:
            - { name: translation.loader, alias: bin }

The alias option is required and very important: it defines the file "suffix" that will be used for the resource files that use this loader. For example, suppose you have some custom bin format that you need to load. If you have a bin file that contains French translations for the messages domain, then you might have a file app/Resources/translations/messages.fr.bin.

When Symfony tries to load the bin file, it passes the path to your custom loader as the $resource argument. You can then perform any logic you need on that file in order to load your translations.

If you're loading translations from a database, you'll still need a resource file, but it might either be blank or contain a little bit of information about loading those resources from the database. The file is key to trigger the load() method on your custom loader.

translation.extractor

Purpose: To register a custom service that extracts messages from a file

When executing the translation:update command, it uses extractors to extract translation messages from a file. By default, the Symfony Framework has a TwigExtractor and a PhpExtractor, which help to find and extract translation keys from Twig templates and PHP files.

You can create your own extractor by creating a class that implements ExtractorInterface and tagging the service with translation.extractor. The tag has one required option: alias, which defines the name of the extractor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// src/Acme/DemoBundle/Translation/FooExtractor.php
namespace Acme\DemoBundle\Translation;

use Symfony\Component\Translation\Extractor\ExtractorInterface;
use Symfony\Component\Translation\MessageCatalogue;

class FooExtractor implements ExtractorInterface
{
    protected $prefix;

    /**
     * Extracts translation messages from a template directory to the catalogue.
     */
    public function extract($directory, MessageCatalogue $catalogue)
    {
        // ...
    }

    /**
     * Sets the prefix that should be used for new found messages.
     */
    public function setPrefix($prefix)
    {
        $this->prefix = $prefix;
    }
}
1
2
3
4
5
services:
    app.custom_translation_extractor:
        class: App\Translation\CustomExtractor
        tags:
            - { name: translation.extractor, alias: foo }

translation.dumper

Purpose: To register a custom service that dumps messages to a file

After a translation extractor has extracted all messages from the templates, the dumpers are executed to dump the messages to a translation file in a specific format.

Symfony already comes with many dumpers:

You can create your own dumper by extending FileDumper or implementing DumperInterface and tagging the service with translation.dumper. The tag has one option: alias This is the name that's used to determine which dumper should be used.

1
2
3
4
5
services:
    app.json_translation_dumper:
        class: AppBundle\Translation\JsonFileDumper
        tags:
            - { name: translation.dumper, alias: json }

See also

Learn how to dump to custom formats in the components section.

twig.extension

Purpose: To register a custom Twig Extension

To enable a Twig extension, add it as a regular service in one of your configuration and tag it with twig.extension:

1
2
3
4
5
services:
    app.twig_extension:
        class: AppBundle\Twig\AppExtension
        tags:
            - { name: twig.extension }

For information on how to create the actual Twig Extension class, see Twig's documentation on the topic or read the How to Write a custom Twig Extension article.

Before writing your own extensions, have a look at the Twig official extension repository which already includes several useful extensions. For example Intl and its localizeddate filter that formats a date according to user's locale. These official Twig extensions also have to be added as regular services:

1
2
3
4
5
services:
    twig.extension.intl:
        class: Twig_Extensions_Extension_Intl
        tags:
            - { name: twig.extension }

twig.loader

Purpose: Register a custom service that loads Twig templates

By default, Symfony uses only one Twig Loader - FilesystemLoader. If you need to load Twig templates from another resource, you can create a service for the new loader and tag it with twig.loader:

1
2
3
4
5
services:
    app.custom_twig_loader:
        class: AppBundle\Twig\CustomLoader
        tags:
            - { name: twig.loader, priority: 0 }

Note

The priority is optional and its value is a positive or negative integer that defaults to 0. Loaders with higher numbers are tried first.

validator.constraint_validator

Purpose: Create your own custom validation constraint

This tag allows you to create and register your own custom validation constraint. For more information, read the How to Create a custom Validation Constraint article.

validator.initializer

Purpose: Register a service that initializes objects before validation

This tag provides a very uncommon piece of functionality that allows you to perform some sort of action on an object right before it's validated. For example, it's used by Doctrine to query for all of the lazily-loaded data on an object before it's validated. Without this, some data on a Doctrine entity would appear to be "missing" when validated, even though this is not really the case.

If you do need to use this tag, just make a new class that implements the ObjectInitializerInterface interface. Then, tag it with the validator.initializer tag (it has no options).

For an example, see the DoctrineInitializer class inside the Doctrine Bridge.

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