Built-in Symfony Service Tags ¶

assets.package ¶

Purpose: Add an asset package to the application

This is an alternative way to declare an asset package. The name of the package is set in this order:

• first, the package attribute of the tag;
  最初に、タグのパッケージ属性。
• then, the value returned by the static method getDefaultPackageName() if defined;
  次に、定義されている場合は静的メソッド getDefaultPackageName() によって返される値。
• finally, the service name.
  最後に、サービス名。

1
2
3
4

services:
    App\Assets\AvatarPackage:
        tags:
            - { name: assets.package, package: avatars }

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Assets\AvatarPackage">
            <tag name="assets.package" package="avatars"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\Assets\AvatarPackage;

$container
    ->register(AvatarPackage::class)
    ->addTag('assets.package', ['package' => 'avatars'])
;

Now you can use the avatars package in your templates:

1

<img src="{{ asset('...', 'avatars') }}">

auto_alias ¶

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

services:
    app.mysql_lock:
        class: App\Lock\MysqlLock
    app.postgresql_lock:
        class: App\Lock\PostgresqlLock
    app.sqlite_lock:
        class: App\Lock\SqliteLock

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="app.mysql_lock"
            class="App\Lock\MysqlLock"/>
        <service id="app.postgresql_lock"
            class="App\Lock\PostgresqlLock"/>
        <service id="app.sqlite_lock"
            class="App\Lock\SqliteLock"/>
    </services>
</container>

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\Lock\MysqlLock;
use App\Lock\PostgresqlLock;
use App\Lock\SqliteLock;

return function(ContainerConfigurator $configurator) {
    $services = $configurator->services();

    $services->set('app.mysql_lock', MysqlLock::class);
    $services->set('app.postgresql_lock', PostgresqlLock::class);
    $services->set('app.sqlite_lock', SqliteLock::class);
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="app.mysql_lock"
            class="App\Lock\MysqlLock"/>
        <service id="app.postgresql_lock"
            class="App\Lock\PostgresqlLock"/>
        <service id="app.sqlite_lock"
            class="App\Lock\SqliteLock"/>

        <service id="app.lock">
            <tag name="auto_alias" format="app.%database_type%_lock"/>
        </service>
    </services>
</container>

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\Lock\MysqlLock;
use App\Lock\PostgresqlLock;
use App\Lock\SqliteLock;

return function(ContainerConfigurator $configurator) {
    $services = $configurator->services();

    $services->set('app.mysql_lock', MysqlLock::class);
    $services->set('app.postgresql_lock', PostgresqlLock::class);
    $services->set('app.sqlite_lock', SqliteLock::class);

    $services->set('app.lock')
        ->tag('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).

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.

container.hot_path ¶

Purpose: Add to list of always needed services

This tag identifies the services that are always needed. It is only applied to a very short list of bootstrapping services (like router, event_dispatcher, http_kernel, request_stack, etc.). Then, it is propagated to all dependencies of these services, with a special case for event listeners, where only listed events are propagated to their related listeners.

It will replace, in cache for generated service factories, the PHP autoload by plain inlined include_once. The benefit is a complete bypass of the autoloader for services and their class hierarchy. The result is a significant performance improvement.

Use this tag with great caution, you have to be sure that the tagged service is always used.

container.no_preload ¶

Purpose: Remove a class from the list of classes preloaded by PHP

Add this tag to a service and its class won't be preloaded when using PHP class preloading:

1
2
3

services:
    App\SomeNamespace\SomeService:
        tags: ['container.no_preload']

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\SomeNamespace\SomeService">
            <tag name="container.no_preload"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\SomeNamespace\SomeService;

$container
    ->register(SomeService::class)
    ->addTag('container.no_preload')
;

If you add some service tagged with container.no_preload as an argument of another service, the container.no_preload tag is applied automatically to that service too.

container.preload ¶

Purpose: Add some class to the list of classes preloaded by PHP

When using PHP class preloading, this tag allows you to define which PHP classes should be preloaded. This can improve performance by making some of the classes used by your service always available for all requests (until the server is restarted):

1
2
3
4
5
6

services:
    App\SomeNamespace\SomeService:
        tags:
            - { name: 'container.preload', class: 'App\SomeClass' }
            - { name: 'container.preload', class: 'App\Some\OtherClass' }
            # ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\SomeNamespace\SomeService">
            <tag name="container.preload" class="App\SomeClass"/>
            <tag name="container.preload" class="App\Some\OtherClass"/>
            <!-- ... -->
        </service>
    </services>
</container>

1
2
3
4
5
6
7
8
9
10

use App\Some\OtherClass;
use App\SomeClass;
use App\SomeNamespace\SomeService;

$container
    ->register(SomeService::class)
    ->addTag('container.preload', ['class' => SomeClass::class])
    ->addTag('container.preload', ['class' => OtherClass::class])
    // ...
;

controller.argument_value_resolver ¶

Purpose: Register a value resolver for controller arguments such as Request

Value resolvers implement the ArgumentValueResolverInterface and are used to resolve argument values for controllers as described here: Built-in Symfony Service Tags.

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 events article.

doctrine.event_subscriber ¶

Purpose: Add a Doctrine event subscriber

For details on creating Doctrine event subscribers, read the Doctrine events 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).

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 a 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

// src/Cache/MyClearer.php
namespace App\Cache;

use Symfony\Component\HttpKernel\CacheClearer\CacheClearerInterface;

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

If you're using the default services.yaml configuration, your service will be automatically tagged with kernel.cache_clearer. But, you can also register it manually:

1
2
3

services:
    App\Cache\MyClearer:
        tags: [kernel.cache_clearer]

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Cache\MyClearer">
            <tag name="kernel.cache_clearer"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\Cache\MyClearer;

$container
    ->register(MyClearer::class)
    ->addTag('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
18
19
20
21
22
23
24
25
26
27
28
29

// src/Cache/MyCustomWarmer.php
namespace App\Cache;

use App\Foo\Bar;
use Symfony\Component\HttpKernel\CacheWarmer\CacheWarmerInterface;

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

        $filesAndClassesToPreload = [];
        $filesAndClassesToPreload[] = Bar::class;

        foreach (scandir($someCacheDir) as $file) {
            if (!is_dir($file = $someCacheDir.'/'.$file)) {
                $filesAndClassesToPreload[] = $file;
            }
        }

        return $filesAndClassesToPreload;
    }

    public function isOptional()
    {
        return true;
    }
}

The warmUp() method must return an array with the files and classes to preload. Files must be absolute paths and classes must be fully-qualified class names. The only restriction is that files must be stored in the cache directory. If you don't need to preload anything, return an empty array.

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

If you're using the default services.yaml configuration, your service will be automatically tagged with kernel.cache_warmer. But, you can also register it manually:

1
2
3
4

services:
    App\Cache\MyCustomWarmer:
        tags:
            - { name: kernel.cache_warmer, priority: 0 }

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Cache\MyCustomWarmer">
            <tag name="kernel.cache_warmer" priority="0"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\Cache\MyCustomWarmer;

$container
    ->register(MyCustomWarmer::class)
    ->addTag('kernel.cache_warmer', ['priority' => 0])
;

In addition to your own cache warmers, Symfony components and third-party bundles define cache warmers too for their own purposes. You can list them all with the following command:

1

$ php bin/console debug:container --tag=kernel.cache_warmer

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.

kernel.event_subscriber ¶

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

This is an alternative way to create an event listener, and is the recommended way (instead of using kernel.event_listener). See Events and Event Listeners.

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.

kernel.locale_aware ¶

Purpose: To access and use the current locale

Setting and retrieving the locale can be done via configuration or using container parameters, listeners, route parameters or the current request.

Thanks to the Translation contract, the locale can be set via services.

To register your own locale aware service, first create a service that implements the LocaleAwareInterface interface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// src/Locale/MyCustomLocaleHandler.php
namespace App\Locale;

use Symfony\Contracts\Translation\LocaleAwareInterface;

class MyCustomLocaleHandler implements LocaleAwareInterface
{
    public function setLocale($locale)
    {
        $this->locale = $locale;
    }

    public function getLocale()
    {
        return $this->locale;
    }
}

If you're using the default services.yaml configuration, your service will be automatically tagged with kernel.locale_aware. But, you can also register it manually:

1
2
3

services:
    App\Locale\MyCustomLocaleHandler:
        tags: [kernel.locale_aware]

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Locale\MyCustomLocaleHandler">
            <tag name="kernel.locale_aware"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\Locale\MyCustomLocaleHandler;

$container
    ->register(LocaleHandler::class)
    ->addTag('kernel.locale_aware')
;

kernel.reset ¶

Purpose: Clean up services between requests

During the kernel.terminate event, Symfony looks for any service tagged with the kernel.reset tag to reinitialize their state. This is done by calling to the method whose name is configured in the method argument of the tag.

This is mostly useful when running your projects in application servers that reuse the Symfony application between requests to improve performance. This tag is applied for example to the built-in data collectors of the profiler to delete all their information.

mime.mime_type_guesser ¶

Purpose: Add your own logic for guessing MIME types

This tag is used to register your own MIME type guessers in case the guessers provided by the Mime component don't fit your needs.

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

services:
    App\Log\CustomLogger:
        arguments: ['@logger']
        tags:
            - { name: monolog.logger, channel: app }

1
2
3
4
5
6
7
8
9
10
11
12
13

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Log\CustomLogger">
            <argument type="service" id="logger"/>
            <tag name="monolog.logger" channel="app"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\Log\CustomLogger;
use Symfony\Component\DependencyInjection\Reference;

$container->register(CustomLogger::class)
    ->addArgument(new Reference('logger'))
    ->addTag('monolog.logger', ['channel' => 'app']);

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

services:
    Monolog\Processor\IntrospectionProcessor:
        tags: [monolog.processor]

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

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

1
2
3
4
5
6

use Monolog\Processor\IntrospectionProcessor;

$container
    ->register(IntrospectionProcessor::class)
    ->addTag('monolog.processor')
;

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

1
2
3
4

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

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

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

1
2
3
4
5
6

use Monolog\Processor\IntrospectionProcessor;

$container
    ->register(IntrospectionProcessor::class)
    ->addTag('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

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

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

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

1
2
3
4
5
6

use Monolog\Processor\IntrospectionProcessor;

$container
    ->register(IntrospectionProcessor::class)
    ->addTag('monolog.processor', ['channel' => 'security'])
;

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

services:
    App\Routing\CustomLoader:
        tags: [routing.loader]

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Routing\CustomLoader">
            <tag name="routing.loader"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\Routing\CustomLoader;

$container
    ->register(CustomLoader::class)
    ->addTag('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.

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

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

1
2
3
4

services:
    App\Translation\MyCustomLoader:
        tags:
            - { name: translation.loader, alias: bin }

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Translation\MyCustomLoader">
            <tag name="translation.loader" alias="bin"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\Translation\MyCustomLoader;

$container
    ->register(MyCustomLoader::class)
    ->addTag('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 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:extract 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 catalog.
     */
    public function extract($directory, MessageCatalogue $catalog)
    {
        // ...
    }

    /**
     * Sets the prefix that should be used for new found messages.
     */
    public function setPrefix(string $prefix)
    {
        $this->prefix = $prefix;
    }
}

1
2
3
4

services:
    App\Translation\CustomExtractor:
        tags:
            - { name: translation.extractor, alias: foo }

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Translation\CustomExtractor">
            <tag name="translation.extractor" alias="foo"/>
        </service>
    </services>
</container>

1
2
3
4

use App\Translation\CustomExtractor;

$container->register(CustomExtractor::class)
    ->addTag('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:

• CsvFileDumper
  Csvファイルダンパー
• IcuResFileDumper
  IcuResFileDumper
• IniFileDumper
  IniFileDumper
• MoFileDumper
  MoFileDumper
• PoFileDumper
  PoFileDumper
• QtFileDumper
  QtFileDumper
• XliffFileDumper
  XliffFileDumper
• YamlFileDumper
  Yamlファイルダンパー

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

services:
    App\Translation\JsonFileDumper:
        tags:
            - { name: translation.dumper, alias: json }

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Translation\JsonFileDumper">
            <tag name="translation.dumper" alias="json"/>
        </service>
    </services>
</container>

1
2
3
4

use App\Translation\JsonFileDumper;

$container->register(JsonFileDumper::class)
    ->addTag('translation.dumper', ['alias' => 'json']);

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. If you're using the default services.yaml configuration, the service is auto-registered and auto-tagged. But, you can also register it manually:

1
2
3
4
5
6
7
8
9

services:
    App\Twig\AppExtension:
        tags: [twig.extension]

    # optionally you can define the priority of the extension (default = 0).
    # Extensions with higher priorities are registered earlier. This is mostly
    # useful to register late extensions that override other extensions.
    App\Twig\AnotherExtension:
        tags: [{ name: twig.extension, priority: -100 }]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Twig\AppExtension">
            <tag name="twig.extension"/>
        </service>

        <service id="App\Twig\AnotherExtension">
            <tag name="twig.extension" priority="-100"/>
        </service>
    </services>
</container>

1
2
3
4
5
6
7
8
9
10
11

use App\Twig\AnotherExtension;
use App\Twig\AppExtension;

$container
    ->register(AppExtension::class)
    ->addTag('twig.extension')
;
$container
    ->register(AnotherExtension::class)
    ->addTag('twig.extension', ['priority' => -100])
;

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.

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.

If you use the default services.yaml configuration, the service will be automatically tagged thanks to autoconfiguration. But, you can also register it manually:

1
2
3
4

services:
    App\Twig\CustomLoader:
        tags:
            - { name: twig.loader, priority: 0 }

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Twig\CustomLoader">
            <tag name="twig.loader" priority="0"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\Twig\CustomLoader;

$container
    ->register(CustomLoader::class)
    ->addTag('twig.loader', ['priority' => 0])
;

twig.runtime ¶

Purpose: To register a custom Lazy-Loaded Twig Extension

Lazy-Loaded Twig Extensions are defined as regular services but they need to be tagged with twig.runtime. If you're using the default services.yaml configuration, the service is auto-registered and auto-tagged. But, you can also register it manually:

1
2
3

services:
    App\Twig\AppExtension:
        tags: [twig.runtime]

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Twig\AppExtension">
            <tag name="twig.runtime"/>
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\Twig\AppExtension;

$container
    ->register(AppExtension::class)
    ->addTag('twig.runtime')
;

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.