[FrameworkBundle] Document the ControllerTrait

GuilhemN · GuilhemN · commit d22543cdd460 · 2017-03-20T22:01:53.000+01:00
diff --git a/controller/service.rst b/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,70 @@ 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\\ControllerTrait` and
+autowire your controller.
+
+.. warning::
+
+    Make sure you know what autowiring is before using it, take a look at
+    :doc:`its documentation </components/dependency_injection/autowiring>`
+    beforehand.
+
+The example above could be revamped to::
+
+    // src/AppBundle/Controller/HelloController.php
+    namespace AppBundle\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\ControllerTrait;
+
+    class HelloController
+    {
+        use ControllerTrait;
+
+        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:
+            app.hello_controller:
+                class: AppBundle\Controller\HelloController
+                autowire: true
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <services>
+            <service id="app.hello_controller" class="AppBundle\Controller\HelloController" autowire="true" />
+        </services>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use AppBundle\Controller\HelloController;
+
+        $container->register('app.hello_controller', HelloController::class)
+            ->setAutowired(true);
+
+.. versionadded:: 3.3
+    The :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\ControllerTrait`
+    was added in Symfony 3.3. Prior to version 3.3, you needed to inject the
+    container in your controller and use the base ``Controller`` class or
+    use alternatives to its shortcut methods.
+
 Referring to the Service
 ------------------------
 
@@ -135,14 +197,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 use autowiring nor the base ``Controller`` class,
+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
