fix(wording): fix on injection name & position

The injection is now named Immutable-setter injection.

As this type of injection is ~better~ as the setter one, his position is now under the constructor one.

Author: Guikingone

service_container/injection_types.rst

@@ -100,25 +100,36 @@ working with optional dependencies. It is also more difficult to use in
 combination with class hierarchies: if a class uses constructor injection
 then extending it and overriding the constructor becomes problematic.
 
-Setter Injection
-----------------
+Immutable-setter Injection
+-------------------
 
-Another possible injection point into a class is by adding a setter method
-that accepts the dependency::
+Another possible injection in to use a method which return ``static``,
+this approach allow you to make a service immutable::
 
     // ...
+
     class NewsletterManager
     {
         private $mailer;
 
-        public function setMailer(MailerInterface $mailer)
+        /**
+         * @required
+         * @return static
+         */
+        public function withMailer(MailerInterface $mailer)
         {
-            $this->mailer = $mailer;
+            $new = clone $this;
+            $new->mailer = $mailer;
+
+            return $new;
         }
 
         // ...
     }
 
+In order to use the full potential of this approach, you can define a third argument
+which allow the container to return the newly created service:
+
 .. configuration-block::
 
     .. code-block:: yaml
@@ -130,7 +141,7 @@ that accepts the dependency::
             app.newsletter_manager:
                 class: App\Mail\NewsletterManager
                 calls:
-                    - [setMailer, ['@mailer']]
+                    - [withMailer, ['@mailer'], true]
 
     .. code-block:: xml
 
@@ -145,7 +156,7 @@ that accepts the dependency::
                 <!-- ... -->
 
                 <service id="app.newsletter_manager" class="App\Mail\NewsletterManager">
-                    <call method="setMailer">
+                    <call method="withMailer" use-result=true>
                         <argument type="service" id="mailer" />
                     </call>
                 </service>
@@ -160,36 +171,55 @@ that accepts the dependency::
 
         // ...
         $container->register('app.newsletter_manager', NewsletterManager::class)
-            ->addMethodCall('setMailer', [new Reference('mailer')]);
+            ->addMethodCall('withMailer', [new Reference('mailer')], true);
 
-This time the advantages are:
+.. note::
 
-* Setter injection works well with optional dependencies. If you do not
-  need the dependency, then do not call the setter.
+    This type of injection requires that you add a ``@return static`` docblock in order
+    for the container to be capable of registering the method.
 
-* You can call the setter multiple times. This is particularly useful if
-  the method adds the dependency to a collection. You can then have a variable
-  number of dependencies.
+This approach is useful if you need to configure your service according to your needs,
+so, what are the advantages?
 
-The disadvantages of setter injection are:
+* Your service becomes immutable, as the container will return a new object,
+  the initial service stays clean and unchanged.
 
-* The setter can be called more than just at the time of construction so
-  you cannot be sure the dependency is not replaced during the lifetime
-  of the object (except by explicitly writing the setter method to check
-  if it has already been called).
+* You can easily change the injected service as long as it respect the interface/type
+  asked by the initial service.
 
-* You cannot be sure the setter will be called and so you need to add checks
-  that any required dependencies are injected.
+* It allow you to get rid of factory usages which can lead a more complex code
 
-Property Injection
-------------------
+* As the dependency is optional, you can easily decide to receive the service
+  without using the "with" method.
 
-Another possibility is setting public fields of the class directly::
+* As the method automatically receive and set the attribute value,
+  you couldn't obtain the newly created service without this dependency.
+
+The disadvantages are:
+
+* 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
+  link your code to the container.
+
+* As this approach force the container to create a new object
+  once the method is called, you can found hard to debug and test your code.
+
+Setter Injection
+----------------
+
+Another possible injection point into a class is by adding a setter method
+that accepts the dependency::
 
     // ...
     class NewsletterManager
     {
-        public $mailer;
+        private $mailer;
+
+        public function setMailer(MailerInterface $mailer)
+        {
+            $this->mailer = $mailer;
+        }
 
         // ...
     }
@@ -204,8 +234,8 @@ Another possibility is setting public fields of the class directly::
 
             app.newsletter_manager:
                 class: App\Mail\NewsletterManager
-                properties:
-                    mailer: '@mailer'
+                calls:
+                    - [setMailer, ['@mailer']]
 
     .. code-block:: xml
 
@@ -220,7 +250,9 @@ Another possibility is setting public fields of the class directly::
                 <!-- ... -->
 
                 <service id="app.newsletter_manager" class="App\Mail\NewsletterManager">
-                    <property name="mailer" type="service" id="mailer" />
+                    <call method="setMailer">
+                        <argument type="service" id="mailer" />
+                    </call>
                 </service>
             </services>
         </container>
@@ -232,53 +264,41 @@ Another possibility is setting public fields of the class directly::
         use Symfony\Component\DependencyInjection\Reference;
 
         // ...
-        $container->register('newsletter_manager', NewsletterManager::class)
-            ->setProperty('mailer', new Reference('mailer'));
+        $container->register('app.newsletter_manager', NewsletterManager::class)
+            ->addMethodCall('setMailer', [new Reference('mailer')]);
 
-There are mainly only disadvantages to using property injection, it is similar
-to setter injection but with these additional important problems:
+This time the advantages are:
 
-* You cannot control when the dependency is set at all, it can be changed
-  at any point in the object's lifetime.
+* Setter injection works well with optional dependencies. If you do not
+  need the dependency, then do not call the setter.
 
-* You cannot use type hinting so you cannot be sure what dependency is injected
-  except by writing into the class code to explicitly test the class instance
-  before using it.
+* You can call the setter multiple times. This is particularly useful if
+  the method adds the dependency to a collection. You can then have a variable
+  number of dependencies.
 
-But, it is useful to know that this can be done with the service container,
-especially if you are working with code that is out of your control, such
-as in a third party library, which uses public properties for its dependencies.
+The disadvantages of setter injection are:
 
-Immutable Injection
--------------------
+* The setter can be called more than just at the time of construction so
+  you cannot be sure the dependency is not replaced during the lifetime
+  of the object (except by explicitly writing the setter method to check
+  if it has already been called).
 
-Another possible injection in to use a method which return ``static``,
-this approach allow you to make a service immutable::
+* You cannot be sure the setter will be called and so you need to add checks
+  that any required dependencies are injected.
 
-    // ...
+Property Injection
+------------------
+
+Another possibility is setting public fields of the class directly::
 
+    // ...
     class NewsletterManager
     {
-        private $mailer;
-        
-        /**
-         * @required
-         * @return static
-         */
-        public function withMailer(MailerInterface $mailer)
-        {
-            $new = clone $this;
-            $new->mailer = $mailer;
-
-            return $new;
-        }
+        public $mailer;
 
         // ...
     }
 
-In order to use the full potential of this approach, you can define a third argument
-which allow the container to return the newly created service:
-
 .. configuration-block::
 
     .. code-block:: yaml
@@ -289,8 +309,8 @@ which allow the container to return the newly created service:
 
             app.newsletter_manager:
                 class: App\Mail\NewsletterManager
-                calls:
-                    - [withMailer, ['@mailer'], true]
+                properties:
+                    mailer: '@mailer'
 
     .. code-block:: xml
 
@@ -305,9 +325,7 @@ which allow the container to return the newly created service:
                 <!-- ... -->
 
                 <service id="app.newsletter_manager" class="App\Mail\NewsletterManager">
-                    <call method="withMailer" use-result=true>
-                        <argument type="service" id="mailer" />
-                    </call>
+                    <property name="mailer" type="service" id="mailer" />
                 </service>
             </services>
         </container>
@@ -319,37 +337,19 @@ which allow the container to return the newly created service:
         use Symfony\Component\DependencyInjection\Reference;
 
         // ...
-        $container->register('app.newsletter_manager', NewsletterManager::class)
-            ->addMethodCall('withMailer', [new Reference('mailer')], true);
-
-.. note::
-
-    This type of injection requires that you add a ``@return static`` docblock in order
-    for the container to be capable of registering the method.
-
-This approach is useful if you need to configure your service according to your needs, 
-so, what are the advantages?
-
-* Your service becomes immutable, as the container will return a new object, 
-  the initial service stays clean and unchanged.
-
-* You can easily change the injected service as long as it respect the interface/type
-  asked by the initial service.
-
-* It allow you to get rid of factory usages which can lead a more complex code
-
-* As the dependency is optional, you can easily decide to receive the service
-  without using the "with" method.
+        $container->register('newsletter_manager', NewsletterManager::class)
+            ->setProperty('mailer', new Reference('mailer'));
 
-* As the method automatically receive and set the attribute value,
-  you couldn't obtain the newly created service without this dependency.
+There are mainly only disadvantages to using property injection, it is similar
+to setter injection but with these additional important problems:
 
-The disadvantages are:
+* You cannot control when the dependency is set at all, it can be changed
+  at any point in the object's lifetime.
 
-* 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
-  link your code to the container.
+* You cannot use type hinting so you cannot be sure what dependency is injected
+  except by writing into the class code to explicitly test the class instance
+  before using it.
 
-* As this approach force the container to create a new object
-  once the method is called, you can found hard to debug and test your code.
+But, it is useful to know that this can be done with the service container,
+especially if you are working with code that is out of your control, such
+as in a third party library, which uses public properties for its dependencies.