dic_tags.rst

The Dependency Injection Tags

Tags:

• data_collector
• form.type
• form.type_extension
• form.type_guesser
• kernel.cache_warmer
• kernel.event_listener
• kernel.event_subscriber
• monolog.logger
• monolog.processor
• templating.helper
• routing.loader
• translation.loader
• twig.extension
• validator.initializer

Enabling Custom PHP Template Helpers

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

services:
    templating.helper.your_helper_name:
        class: Fully\Qualified\Helper\Class\Name
        tags:
            - { name: templating.helper, alias: alias_name }

<service id="templating.helper.your_helper_name" class="Fully\Qualified\Helper\Class\Name">
    <tag name="templating.helper" alias="alias_name" />
</service>

$container
    ->register('templating.helper.your_helper_name', 'Fully\Qualified\Helper\Class\Name')
    ->addTag('templating.helper', array('alias' => 'alias_name'))
;

Enabling Custom Twig Extensions

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

services:
    twig.extension.your_extension_name:
        class: Fully\Qualified\Extension\Class\Name
        tags:
            - { name: twig.extension }

<service id="twig.extension.your_extension_name" class="Fully\Qualified\Extension\Class\Name">
    <tag name="twig.extension" />
</service>

$container
    ->register('twig.extension.your_extension_name', 'Fully\Qualified\Extension\Class\Name')
    ->addTag('twig.extension')
;

For information on how to create the actual Twig Extension class, see Twig's documentation on the topic.

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:

services:
    twig.extension.intl:
        class: Twig_Extensions_Extension_Intl
        tags:
            - { name: twig.extension }

<service id="twig.extension.intl" class="Twig_Extensions_Extension_Intl">
    <tag name="twig.extension" />
</service>

$container
    ->register('twig.extension.intl', 'Twig_Extensions_Extension_Intl')
    ->addTag('twig.extension')
;

Enabling Custom Listeners

To enable a custom listener, add it as a regular service in one of your configuration, and tag it with kernel.event_listener. You must provide the name of the event your service listens to, as well as the method that will be called:

services:
    kernel.listener.your_listener_name:
        class: Fully\Qualified\Listener\Class\Name
        tags:
            - { name: kernel.event_listener, event: xxx, method: onXxx }

<service id="kernel.listener.your_listener_name" class="Fully\Qualified\Listener\Class\Name">
    <tag name="kernel.event_listener" event="xxx" method="onXxx" />
</service>

$container
    ->register('kernel.listener.your_listener_name', 'Fully\Qualified\Listener\Class\Name')
    ->addTag('kernel.event_listener', array('event' => 'xxx', 'method' => 'onXxx'))
;

Note

You can also specify priority as an attribute of the kernel.event_listener tag (much like the method or event attributes), with either a positive or negative integer. This allows you to make sure your listener will always be called before or after another listener listening for the same event.

Enabling Custom Subscribers

2.1

The ability to add kernel event subscribers is new to 2.1.

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

services:
    kernel.subscriber.your_subscriber_name:
        class: Fully\Qualified\Subscriber\Class\Name
        tags:
            - { name: kernel.event_subscriber }

<service id="kernel.subscriber.your_subscriber_name" class="Fully\Qualified\Subscriber\Class\Name">
    <tag name="kernel.event_subscriber" />
</service>

$container
    ->register('kernel.subscriber.your_subscriber_name', 'Fully\Qualified\Subscriber\Class\Name')
    ->addTag('kernel.event_subscriber')
;

Note

Your service must implement the Symfony\Component\EventDispatcher\EventSubscriberInterface interface.

Note

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

Enabling Custom Template Engines

To enable a custom template engine, add it as a regular service in one of your configuration, tag it with templating.engine:

services:
    templating.engine.your_engine_name:
        class: Fully\Qualified\Engine\Class\Name
        tags:
            - { name: templating.engine }

<service id="templating.engine.your_engine_name" class="Fully\Qualified\Engine\Class\Name">
    <tag name="templating.engine" />
</service>

$container
    ->register('templating.engine.your_engine_name', 'Fully\Qualified\Engine\Class\Name')
    ->addTag('templating.engine')
;

Enabling Custom Routing Loaders

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

services:
    routing.loader.your_loader_name:
        class: Fully\Qualified\Loader\Class\Name
        tags:
            - { name: routing.loader }

<service id="routing.loader.your_loader_name" class="Fully\Qualified\Loader\Class\Name">
    <tag name="routing.loader" />
</service>

$container
    ->register('routing.loader.your_loader_name', 'Fully\Qualified\Loader\Class\Name')
    ->addTag('routing.loader')
;

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

services:
    my_service:
        class: Fully\Qualified\Loader\Class\Name
        arguments: [@logger]
        tags:
            - { name: monolog.logger, channel: acme }

<service id="my_service" class="Fully\Qualified\Loader\Class\Name">
    <argument type="service" id="logger" />
    <tag name="monolog.logger" channel="acme" />
</service>

$definition = new Definition('Fully\Qualified\Loader\Class\Name', array(new Reference('logger'));
$definition->addTag('monolog.logger', array('channel' => 'acme'));
$container->register('my_service', $definition);;

Note

This works only when the logger service is a constructor argument, not when it is injected through a setter.

Adding a processor for Monolog

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.

Let's see how you can use the built-in IntrospectionProcessor to add the file, the line, the class and the method where the logger was triggered.

You can add a processor globally:

services:
    my_service:
        class: Monolog\Processor\IntrospectionProcessor
        tags:
            - { name: monolog.processor }

<service id="my_service" class="Monolog\Processor\IntrospectionProcessor">
    <tag name="monolog.processor" />
</service>

$definition = new Definition('Monolog\Processor\IntrospectionProcessor');
$definition->addTag('monolog.processor');
$container->register('my_service', $definition);

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:

services:
    my_service:
        class: Monolog\Processor\IntrospectionProcessor
        tags:
            - { name: monolog.processor, handler: firephp }

<service id="my_service" class="Monolog\Processor\IntrospectionProcessor">
    <tag name="monolog.processor" handler="firephp" />
</service>

$definition = new Definition('Monolog\Processor\IntrospectionProcessor');
$definition->addTag('monolog.processor', array('handler' => 'firephp');
$container->register('my_service', $definition);

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:

services:
    my_service:
        class: Monolog\Processor\IntrospectionProcessor
        tags:
            - { name: monolog.processor, channel: security }

<service id="my_service" class="Monolog\Processor\IntrospectionProcessor">
    <tag name="monolog.processor" channel="security" />
</service>

$definition = new Definition('Monolog\Processor\IntrospectionProcessor');
$definition->addTag('monolog.processor', array('channel' => 'security');
$container->register('my_service', $definition);

Note

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