refactor(service_container): refactoring on pros & cons + calls

Author: Guikingone

service_container/calls.rst

@@ -110,7 +110,7 @@ In order to use this approach fully, just adapt the container configuration:
             App\Service\MessageGenerator:
                 # ...
                 calls:
-                    - method: setLogger
+                    - method: withLogger
                       arguments:
                           - '@logger'
                        use_result: true
@@ -127,7 +127,7 @@ In order to use this approach fully, just adapt the container configuration:
             <services>
                 <service id="App\Service\MessageGenerator">
                     <!-- ... -->
-                    <call method="setLogger" use-result="true">
+                    <call method="withLogger" use-result="true">
                         <argument type="service" id="logger" />
                     </call>
                 </service>
@@ -141,4 +141,4 @@ In order to use this approach fully, just adapt the container configuration:
         use Symfony\Component\DependencyInjection\Reference;
 
         $container->register(MessageGenerator::class)
-            ->addMethodCall('setLogger', [new Reference('logger')], true);
+            ->addMethodCall('withLogger', [new Reference('logger')], true);

service_container/injection_types.rst

@@ -181,6 +181,12 @@ which allow the container to return the newly created service:
 This approach is useful if you need to configure your service according to your needs,
 so, what are the advantages?
 
+* Immutable setters works with optional dependencies, this way, if you don't need
+  a dependency, the setter don't need to be called.
+
+* Like the constructor injection, using immutable setters force the dependency to stay
+  the same during the lifetime of a service.
+
 * Your service becomes immutable, as the container will return a new object,
   the initial service stays clean and unchanged.
 
@@ -189,6 +195,9 @@ so, what are the advantages?
 
 The disadvantages are:
 
+* As the setter call is optional, a dependency can be null during execution,
+  you must check that the dependency is available before calling it.
+
 * As the ``@return static`` docblock is required by the container to
   understand that the method return a new object,
   you can found that adding docblock for a single method isn't adapted or