feat(code): progress on immutable-setter usage

The definitions have been improved.

The calls have been updated.

Author: Guikingone

service_container/calls.rst

@@ -71,3 +71,74 @@ To configure the container to call the ``setLogger`` method, use the ``calls`` k
 
         $container->register(MessageGenerator::class)
             ->addMethodCall('setLogger', [new Reference('logger')]);
+
+When it comes to optional dependencies, the setter approach can be useful but
+what if you need to change the injected dependency without mutating the initial service?
+
+To do so, you probably could use `immutable-setter` injection::
+
+    namespace App\Service;
+
+    use Psr\Log\LoggerInterface;
+
+    class MessageGenerator
+    {
+        private $logger;
+
+        /**
+         * @return static
+         */
+        public function withLogger(LoggerInterface $logger)
+        {
+            $new = clone $this;
+            $new->logger = $logger;
+
+            return $new;
+        }
+
+        // ...
+    }
+
+In order to use this approach fully, just adapt the container configuration:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\Service\MessageGenerator:
+                # ...
+                calls:
+                    - method: setLogger
+                      arguments:
+                          - '@logger'
+                       use_result: true
+
+    .. code-block:: xml
+
+        <!-- config/services.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\Service\MessageGenerator">
+                    <!-- ... -->
+                    <call method="setLogger" use-result="true">
+                        <argument type="service" id="logger" />
+                    </call>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use App\Service\MessageGenerator;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        $container->register(MessageGenerator::class)
+            ->addMethodCall('setLogger', [new Reference('logger')], true);

service_container/definitions.rst

@@ -117,6 +117,9 @@ any method calls in the definitions as well::
     // configures a new method call
     $definition->addMethodCall('setLogger', [new Reference('logger')]);
 
+    // configure immutable-setter
+    $definition->addMethodCall('withLogger', [new Reference('logger')], true);
+
     // replaces all previously configured method calls with the passed array
     $definition->setMethodCalls($methodCalls);