diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index e4db9851aaa..56013b4a52e 100644 --- a/reference/dic_tags.rst +++ b/reference/dic_tags.rst @@ -22,6 +22,7 @@ Tag Name Usage `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 @@ -227,6 +228,120 @@ assetic.templating.twig The tagged service will be removed from the container if ``framework.templating.engines`` config section does not contain ``twig``. +auto_alias +---------- + +.. versionadded:: 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: + +.. configuration-block:: + + .. code-block:: yaml + + services: + app.mysql_lock: + class: AppBundle\Lock\MysqlLock + app.postgresql_lock: + class: AppBundle\Lock\PostgresqlLock + app.sqlite_lock: + class: AppBundle\Lock\SqliteLock + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + $container + ->register('app.mysql_lock', 'AppBundle\Lock\MysqlLock') + ->register('app.postgresql_lock', 'AppBundle\Lock\PostgresqlLock') + ->register('app.sqlite_lock', 'AppBundle\Lock\SqliteLock') + ; + +Instead of dealing with these three services, your application needs a generic +``app.lock`` service. This service must be an alias to any of the other services. +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, +the generic ``app.lock`` service can be defined as follows: + +.. configuration-block:: + + .. code-block:: yaml + + 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 + app.lock: + tags: + - { name: auto_alias, format: "app.%database_type%_lock" } + + .. code-block:: xml + + + + + + + + + + + + + + + + .. code-block:: php + + $container + ->register('app.mysql_lock', 'AppBundle\Lock\MysqlLock')->setPublic(false) + ->register('app.postgresql_lock', 'AppBundle\Lock\PostgresqlLock')->setPublic(false) + ->register('app.sqlite_lock', 'AppBundle\Lock\SqliteLock')->setPublic(false) + + ->register('app.lock') + ->addTag('auto_alias', array('format' => 'app.%database_type%_lock')) + ; + +The ``format`` parameter 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. + console.command ---------------