[FrameworkBundle] Document the AbstractController

Author: GuilhemN

controller/service.rst

@@ -29,11 +29,9 @@ These are the main **advantages** of defining controllers as services:
 These are the main **drawbacks** of defining controllers as services:
 
 * It takes more work to create the controllers because they don't have
-  automatic access to the services or to the base controller shortcuts;
+  automatic access to the services;
 * The constructor of the controllers can rapidly become too complex because you
   must inject every single dependency needed by them;
-* The code of the controllers is more verbose because you can't use the shortcuts
-  of the base controller and you must replace them with some lines of code.
 
 The recommendation from the :doc:`best practices </best_practices/controllers>`
 is also valid for controllers defined as services: avoid putting your business
@@ -83,6 +81,74 @@ Then you can define it as a service as follows:
 
         $container->register('app.hello_controller', HelloController::class);
 
+Using the controller shortcuts
+------------------------------
+
+To use the traditional controller shortcuts, you can use the
+:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class if you
+need to access the container or the
+:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController` class
+if you prefer explicit injection (you can't access the container).
+
+The example above could be revamped to::
+
+    // src/AppBundle/Controller/HelloController.php
+    namespace AppBundle\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+
+    class HelloController extends AbstractController
+    {
+        public function indexAction($name)
+        {
+            // renders app/Resources/views/hello/index.html.twig
+            return $this->render('hello/index.html.twig', array('name' => $name));
+        }
+    }
+
+With the following configuration:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            _instanceof:
+                Symfony\Bundle\FrameworkBundle\Controller\AbstractController:
+                    calls: [ [ setContainer, [ '@container' ] ] ]
+                    tags: [ container.service_subscriber ]
+
+            AppBundle\Controller\HelloController: ~
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <services>
+            <instanceof id="Symfony\Bundle\FrameworkBundle\Controller\AbstractController">
+                <call method="setController">
+                    <argument type="service" id="container" />
+                </call>
+                <tag name="container.service_subscriber" />
+            </instanceof>
+
+            <service id="AppBundle\Controller\HelloController" />
+        </services>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use AppBundle\Controller\HelloController;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        $container->register(HelloController::class)
+            ->addMethodCall('setContainer', new Reference('container'));
+
+.. versionadded:: 3.3
+    The :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`
+    class was added in Symfony 3.3. Prior to version 3.3, you needed to use the
+    base ``Controller`` class or use alternatives to its shortcut methods.
+
 Referring to the Service
 ------------------------
 
@@ -135,14 +201,15 @@ the route ``_controller`` value:
     If your controller implements the ``__invoke()`` method, you can simply
     refer to the service id (``app.hello_controller``).
 
-Alternatives to base Controller Methods
----------------------------------------
+Alternatives to Controller shortcut Methods
+-------------------------------------------
 
-When using a controller defined as a service, it will most likely not extend
-the base ``Controller`` class. Instead of relying on its shortcut methods,
-you'll interact directly with the services that you need. Fortunately, this is
-usually pretty easy and the base `Controller class source code`_ is a great
-source on how to perform many common tasks.
+In case you don't want to inject the container in your controllers,
+it's possible to get ride of controller shortcut methods: you can interact
+directly with the services that you need.
+Fortunately, this is usually pretty easy and the base
+`Controller class source code`_ is a great source on how to perform many common
+tasks.
 
 For example, if you want to render a template instead of creating the ``Response``
 object directly, then your code would look like this if you were extending