update

Author: GuilhemN

best_practices/security.rst

@@ -328,18 +328,9 @@ the same ``getAuthorEmail()`` logic you used above:
         }
     }
 
-To enable the security voter in the application, define a new service:
-
-.. code-block:: yaml
-
-    # app/config/services.yml
-    services:
-        # ...
-        app.post_voter:
-            class:      AppBundle\Security\PostVoter
-            arguments: ['@security.access.decision_manager']
-            public:     false
-            tags: [security.voter]
+Your application will :ref:`autoconfigure <services-autoconfigure>` your security
+voter and inject a ``AccessDecisionManagerInterface`` instance in it thanks to
+:doc:`autowiring </service_container/autowiring>`.
 
 Now, you can use the voter with the ``@Security`` annotation:
 

service_container/autowiring.rst

@@ -86,13 +86,26 @@ autowired:
 
 The autowiring subsystem will detect the dependencies of the ``TwitterClient``
 class by parsing its constructor. For instance it will find here an instance of
-a ``Rot13Transformer`` as dependency. If an existing service definition (and only
-one – see below) is of the required type, this service will be injected. If it's
-not the case (like in this example), the subsystem is smart enough to automatically
-register a private service for the ``Rot13Transformer`` class and set it as first
-argument of the ``twitter_client`` service. Again, it can work only if there is one
-class of the given type. If there are several classes of the same type, you must
-use an explicit service definition or register a default implementation.
+a ``Rot13Transformer`` as dependency.
+
+The subsystem will first try to find a service whose id is the FQCN (fully-qualified
+class name) of the type hint, so here it'll search for a service named
+``AppBundle\Rot13Transformer``.
+
+In case this service does not exist, the subsystem will detect the types of all
+services and check if one - and only one - implements the required type, and
+inject it if it's the case. If there are several services of the same type, an
+exception will be thrown. You'll have to use an explicit service definition or
+register a default implementation by creating a service or an alias whose id is
+the FQCN of the required type.
+Note that this check is deprecated and will be removed in 4.0. The subsystem
+will directly pass to the last option it has.
+
+At last, if no service implements the required type, as it's the case here, the
+subsystem is, as long as it's a concrete class, smart enough to automatically
+register a private service for it.
+Here it'll register a private service for the ``Rot13Transformer`` class and set
+it as first argument of the ``twitter_client`` service.
 
 As you can see, the autowiring feature drastically reduces the amount of configuration
 required to define a service. No more arguments section! It also makes it easy
@@ -185,7 +198,9 @@ And update ``TwitterClient`` to depend of this new interface::
     }
 
 Finally the service definition must be updated because, obviously, the autowiring
-subsystem isn't able to find itself the interface implementation to register:
+subsystem isn't able to find itself the interface implementation to register.
+You have to indicate which service must be injected for your interface when
+using autowiring:
 
 .. configuration-block::
 
@@ -194,6 +209,10 @@ subsystem isn't able to find itself the interface implementation to register:
         services:
             AppBundle\Rot13Transformer: ~
 
+            # the ``AppBundle\Rot13Transformer`` service will be injected when
+            # a ``AppBundle\TransformerInterface`` type-hint is detected
+            AppBundle\TransformerInterface: '@AppBundle\Rot13Transformer'
+
             AppBundle\TwitterClient:
                 autowire: true
 
@@ -207,6 +226,8 @@ subsystem isn't able to find itself the interface implementation to register:
             <services>
                 <service id="AppBundle\Rot13Transformer" />
 
+                <service id="AppBundle\TransformerInterface" alias="AppBundle\Rot13Transformer" />
+
                 <service id="AppBundle\TwitterClient" autowire="true" />
             </services>
         </container>
@@ -218,21 +239,26 @@ subsystem isn't able to find itself the interface implementation to register:
 
         // ...
         $container->register(Rot13Transformer::class);
+        $container->setAlias(TransformerInterface::class, Rot13Transformer::class);
+
         $container->autowire(TwitterClient::class);
 
-The autowiring subsystem detects that the ``AppBundle\Rot13Transformer`` service
-implements the ``TransformerInterface`` and injects it automatically. Even when
-using interfaces (and you should), building the service graph and refactoring
-the project is easier than with standard definitions.
+The autowiring subsystem knows that the ``AppBundle\Rot13Transformer`` service
+must be injected when dealing with the ``TransformerInterface`` and injects it
+automatically. Even when using interfaces (and you should), building the service
+graph and refactoring the project is easier than with standard definitions.
 
 .. _service-autowiring-alias:
 
 Dealing with Multiple Implementations of the Same Type
 ------------------------------------------------------
 
-Last but not least, the autowiring feature allows to specify the default implementation
-of a given type. Let's introduce a new implementation of the ``TransformerInterface``
-returning the result of the ROT13 transformation uppercased::
+When you defined aliases whose id were FQCN earlier, you told the autowiring
+subsystem which service was the default implementation for those FQCN.
+So if you have several services implementing the same type, you can decide which
+one the subsystem should use. Let's introduce a new implementation of the
+``TransformerInterface`` returning the result of the ROT13 transformation
+uppercased::
 
     namespace AppBundle;
 
@@ -274,6 +300,9 @@ transformer::
          */
         public function tweetAction(Request $request, TwitterClient $twitterClient)
         {
+            // Here the client is directly injected because it's the default
+            // implementation
+
             return $this->tweet($request, $twitterClient);
         }
 
@@ -315,6 +344,9 @@ and a Twitter client using it:
         services:
             AppBundle\Rot13Transformer: ~
 
+            # the ``AppBundle\Rot13Transformer`` service will *always* be used
+            # when ``AppBundle\TransformerInterface`` is detected by the
+            # autowiring subsystem
             AppBundle\TransformerInterface: '@AppBundle\Rot13Transformer'
 
             AppBundle\TwitterClient:
@@ -359,7 +391,7 @@ and a Twitter client using it:
 
         // ...
         $container->register(Rot13Transformer::class);
-        $container->setAlias(TransformerInterface::class, Rot13Transformer::class)
+        $container->setAlias(TransformerInterface::class, Rot13Transformer::class);
 
         $container->autowire(TwitterClient::class);
         $container->autowire(UppercaseTransformer::class);