Document how to use named aliases

Author: greg0ire

service_container/autowiring.rst

@@ -363,9 +363,37 @@ If you register this as a service, you now have *two* services that implement th
 which one to use. Remember, autowiring isn't magic; it looks for a service
 whose id matches the type-hint. So you need to choose one by creating an alias
 from the type to the correct service id (see :ref:`autowiring-interface-alias`).
+Additionally, you can define several named aliases if you want to use
+one implementation in some cases, and another implementation in some
+other cases.
 
-If you want ``Rot13Transformer`` to be the service that's used for autowiring, create
-that alias:
+If you want ``Rot13Transformer`` to be the service that's used for
+autowiring by default, and use ``UppercaseTransformer`` in some special
+cases, you can create a simple alias from the interface to
+``Rot13Transformer``, and then create a *named alias* from a special
+string containing the interface followed by a variable named you will
+have to use when doing the injection::
+
+    namespace App\Service;
+
+    use App\Util\TransformerInterface;
+
+    class MastodonClient
+    {
+        private $transformer;
+
+        public function __construct(TransformerInterface $shoutyTransformer)
+        {
+            $this->transformer = $shoutyTransformer;
+        }
+
+        public function toot($user, $key, $status)
+        {
+            $transformedStatus = $this->transformer->transform($status);
+
+            // ... connect to Mastodon and send the transformed status
+        }
+    }
 
 .. configuration-block::
 
@@ -378,15 +406,21 @@ that alias:
             App\Util\Rot13Transformer: ~
             App\Util\UppercaseTransformer: ~
 
+            # the ``App\Util\UppercaseTransformer`` service will be
+            # injected when an ``App\Util\TransformerInterface``
+            # type-hint for a ``$shoutyTransformer`` argument is detected.
             # the ``App\Util\Rot13Transformer`` service will be injected when
-            # a ``App\Util\TransformerInterface`` type-hint is detected
+            # an ``App\Util\TransformerInterface`` type-hint is detected,
+            # but the argument name does not match that of a named alias
             App\Util\TransformerInterface: '@App\Util\Rot13Transformer'
+            App\Util\TransformerInterface $shoutyTransformer: '@App\Util\UppercaseTransformer'
 
             App\Service\TwitterClient:
                 # the Rot13Transformer will be passed as the $transformer argument
                 autowire: true
 
-                # If you wanted to choose the non-default service, wire it manually
+                # If you wanted to choose the non-default service and
+                # do not want to use a named alias, wire it manually
                 # arguments:
                 #     $transformer: '@App\Util\UppercaseTransformer'
                 # ...
@@ -405,6 +439,9 @@ that alias:
                 <service id="App\Util\UppercaseTransformer"/>
 
                 <service id="App\Util\TransformerInterface" alias="App\Util\Rot13Transformer"/>
+                <service
+                    id="App\Util\TransformerInterface $shoutyTransformer"
+                    alias="App\Util\UppercaseTransformer"/>
 
                 <service id="App\Service\TwitterClient" autowire="true">
                     <!-- <argument key="$transformer" type="service" id="App\Util\UppercaseTransformer"/> -->
@@ -419,6 +456,7 @@ that alias:
         use App\Util\UppercaseTransformer;
         use App\Util\TransformerInterface;
         use App\Service\TwitterClient;
+        use App\Service\MastodonClient;
 
         // ...
         $container->autowire(Rot13Transformer::class);
@@ -427,12 +465,23 @@ that alias:
         $container->autowire(TwitterClient::class)
             //->setArgument('$transformer', new Reference(UppercaseTransformer::class))
         ;
+        $container->registerAliasForArgument(
+            TransformerInterface::class,
+            MastodonClient::class,
+            'shoutyVariable'
+        );
 
 Thanks to the ``App\Util\TransformerInterface`` alias, any argument type-hinted
 with this interface will be passed the ``App\Util\Rot13Transformer`` service.
-But, you can also manually wire the *other* service by specifying the argument
+If the argument is named ``$shoutyTransformer``,
+``App\Util\UppercaseTransformer`` will be used instead.
+But, you can also manually wire any *other* service by specifying the argument
 under the arguments key.
 
+.. versionadded:: 4.2
+
+    Named aliases have been introduced in Symfony 4.2
+
 Fixing Non-Autowireable Arguments
 ---------------------------------