From a3abf25d39ce76c661af799af10348f77e07aa88 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Mon, 26 Mar 2018 17:34:04 +0200
Subject: [PATCH] Documented the autowiring of the decorated services

---
 service_container/service_decoration.rst | 68 +++++++++++++++++++-----
 1 file changed, 56 insertions(+), 12 deletions(-)

diff --git a/service_container/service_decoration.rst b/service_container/service_decoration.rst
index 43c1a03c444..1710a24d2f2 100644
--- a/service_container/service_decoration.rst
+++ b/service_container/service_decoration.rst
@@ -62,16 +62,66 @@ that you can reference it:
             App\Mailer: ~
 
             App\DecoratingMailer:
-                # overrides the App\Mailer service
-                # but that service is still available as App\Mailer.inner
                 decorates: App\Mailer
 
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
+            xsd:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="App\Mailer" />
+
+                <service id="App\DecoratingMailer"
+                    decorates="App\Mailer"
+                />
+
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use App\DecoratingMailer;
+        use App\Mailer;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        $container->register(Mailer::class);
+
+        $container->register(DecoratingMailer::class)
+            ->setDecoratedService(Mailer::class)
+        ;
+
+The ``decorates`` option tells the container that the ``App\DecoratingMailer``
+service replaces the ``App\Mailer`` service. If you're using the
+:ref:`default services.yaml configuration <service-container-services-load-example>`,
+the decorated service is automatically injected into the decorating service
+constructor. The name of the argument is ``decorating_service_id + '.inner'``
+(in this example, ``App\DecoratingMailer.inner``).
+
+.. versionadded:: 4.1
+    The autowiring of the decorated service was introduced in Symfony 4.1.
+
+If you are not using autowiring or the decorating service has more than one
+constructor argument of the type of the decorated service, you must inject the
+decorated service explicitly:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\Mailer: ~
+
+            App\DecoratingMailer:
+                decorates: App\Mailer
                 # pass the old service as an argument
                 arguments: ['@App\DecoratingMailer.inner']
 
-                # private, because usually you do not need to fetch App\DecoratingMailer directly
-                public:    false
-
     .. code-block:: xml
 
         <!-- config/services.xml -->
@@ -85,7 +135,6 @@ that you can reference it:
 
                 <service id="App\DecoratingMailer"
                     decorates="App\Mailer"
-                    public="false"
                 >
                     <argument type="service" id="App\DecoratingMailer.inner" />
                 </service>
@@ -105,16 +154,11 @@ that you can reference it:
         $container->register(DecoratingMailer::class)
             ->setDecoratedService(Mailer::class)
             ->addArgument(new Reference(DecoratingMailer::class.'.inner'))
-            ->setPublic(false)
         ;
 
-The ``decorates`` option tells the container that the ``App\DecoratingMailer`` service
-replaces the ``App\Mailer`` service. The old ``App\Mailer`` service is renamed to
-``App\DecoratingMailer.inner`` so you can inject it into your new service.
-
 .. tip::
 
-    The visibility (public) of the decorated ``App\Mailer`` service (which is an alias
+    The visibility of the decorated ``App\Mailer`` service (which is an alias
     for the new service) will still be the same as the original ``App\Mailer``
     visibility.