Merge branch '4.2'

wouterj · wouterj · commit ebf693bcafd7 · 2019-04-09T21:46:07.000+02:00
* 4.2: minor #11386 Update cache.rst (poliveras) [Cache] Syntax fix Update cache.rst Document how to use named aliases
diff --git a/cache.rst b/cache.rst
@@ -51,7 +51,7 @@ of:
     provider then a service is automatically created.
 
 There are two pools that are always enabled by default. They are ``cache.app`` and
-``cache.system``. The system cache is use for things like annotations, serializer,
+``cache.system``. The system cache is used for things like annotations, serializer,
 and validation. The ``cache.app`` can be used in your code. You can configure which
 adapter (template) they use by using the ``app`` and ``system`` key like:
 
@@ -329,7 +329,7 @@ For advanced configurations it could sometimes be useful to use a pool as an ada
 Custom Provider Options
 -----------------------
 
-Some providers have specific options that could be configured. The
+Some providers have specific options that can be configured. The
 :doc:`RedisAdapter </components/cache/adapters/redis_adapter>` allows you to
 create providers with option ``timeout``, ``retry_interval``. etc. To use these
 options with non-default values you need to create your own ``\Redis`` provider
@@ -355,7 +355,7 @@ and use that when configuring the pool.
                     - 'redis://localhost'
                     - [ retry_interval: 2, timeout: 10 ]
 
-.. code-block:: xml
+    .. code-block:: xml
 
         <!-- config/packages/cache.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
@@ -406,7 +406,7 @@ and use that when configuring the pool.
 Creating a Cache Chain
 ----------------------
 
-Different cache adapters has different strengths and weaknesses. Some might be really
+Different cache adapters have different strengths and weaknesses. Some might be really
 quick but small and some may be able to contain a lot of data but are quite slow.
 To get the best of both worlds you may use a chain of adapters. The idea is to
 first look at the quick adapter and then move on to slower adapters. In the worst
diff --git a/service_container/autowiring.rst b/service_container/autowiring.rst
@@ -363,9 +363,40 @@ 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:
+
+For instance, you may want to use by default the ``Rot13Transformer``
+implementation by default when the ``TransformerInterface`` interface is
+type hinted, but use the ``UppercaseTransformer`` implementation in some
+specific cases. To do so, you can create a normal alias from the
+``TransformerInterface`` interface to ``Rot13Transformer``, and then
+create a *named alias* from a special string containing the interface
+followed by a variable name matching the one you 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 +409,22 @@ that alias:
             App\Util\Rot13Transformer: ~
             App\Util\UppercaseTransformer: ~
 
-            # the ``App\Util\Rot13Transformer`` service will be injected when
-            # a ``App\Util\TransformerInterface`` type-hint is detected
+            # the ``App\Util\UppercaseTransformer`` service will be
+            # injected when an ``App\Util\TransformerInterface``
+            # type-hint for a ``$shoutyTransformer`` argument is detected.
             App\Util\TransformerInterface: '@App\Util\Rot13Transformer'
 
+            # If the argument used for injection does not match, but the
+            # type-hint still matches, the ``App\Util\Rot13Transformer``
+            # service will be injected.
+            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 +443,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"/> -->
@@ -418,21 +459,33 @@ that alias:
         use App\Util\Rot13Transformer;
         use App\Util\UppercaseTransformer;
         use App\Util\TransformerInterface;
+        use App\Service\MastodonClient;
         use App\Service\TwitterClient;
 
         // ...
         $container->autowire(Rot13Transformer::class);
         $container->autowire(UppercaseTransformer::class);
         $container->setAlias(TransformerInterface::class, Rot13Transformer::class);
+        $container->setAlias(
+            TransformerInterface::class.' $shoutyTransformer',
+            UppercaseTransformer::class
+        );
         $container->autowire(TwitterClient::class)
             //->setArgument('$transformer', new Reference(UppercaseTransformer::class))
         ;
+        $container->autowire(MastodonClient::class);
 
 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
 ---------------------------------
 
