feature #5444 Documented the "auto_alias" feature (javiereguiluz)

weaverryan · weaverryan · commit 963ed7f4e32b · 2015-07-15T20:28:59.000-04:00
This PR was merged into the 2.7 branch. Discussion ---------- Documented the "auto_alias" feature | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | 2.7+ | Fixed tickets | #4992 Commits ------- 1524f5a Fixed an error in the auto_alias format value bab745d Minor grammar issue 4d0f6ea Minor fixes 4c50cb0 Fixed some errors and added a new note e24f77e Removed an extra blank line 69152e7 Added the "versionadded: 2.7" directive a5f0eec Documented the "auto_alias" feature
diff --git 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
+
+        <?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 http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.mysql_lock" class="AppBundle\Lock\MysqlLock" />
+                <service id="app.postgresql_lock" class="AppBundle\Lock\PostgresqlLock" />
+                <service id="app.sqlite_lock" class="AppBundle\Lock\SqliteLock" />
+            </services>
+        </container>
+
+    .. 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
+
+        <?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 http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.mysql_lock" public="false"
+                         class="AppBundle\Lock\MysqlLock" />
+                <service id="app.postgresql_lock" public="false"
+                         class="AppBundle\Lock\PostgresqlLock" />
+                <service id="app.sqlite_lock" public="false"
+                         class="AppBundle\Lock\SqliteLock" />
+
+                <service id="app.lock">
+                    <tag name="auto_alias" format="app.%database_type%_lock" />
+                </service>
+            </services>
+        </container>
+
+    .. 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
 ---------------
 
