feature #6611 Discourage the use of controllers as services (javiereguiluz)

This PR was submitted for the 2.3 branch but it was merged into the 2.7 branch instead (closes #6611).

Discussion
----------

Discourage the use of controllers as services

As briefly discussed during the past Docs Hack Day, the official Symfony opinion about "controllers as services" is very clear: don't do it, unless you know well what you are doing.

I propose to remove most of the mentions to "controllers as services" to not confuse readers about something we don't want them to use.

Commits
-------

a1847fb Minor fix
deaa5fc Fixed typo
abc7cf3 Discourage the use of controllers as services

Author: weaverryan

book/controller.rst

@@ -399,14 +399,6 @@ that's available to you with or without the use of the base
 action is to look in the
 :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class.
 
-.. seealso::
-
-    If you're curious about how a controller would work that did *not*
-    extend this base ``Controller`` class, check out cookbook article
-    :doc:`Controllers as Services </cookbook/controller/service>`.
-    This is optional, but can give you more control over the exact
-    objects/dependencies that are injected into your controller.
-
 .. index::
    single: Controller; Redirecting
 

book/service_container.rst

@@ -152,9 +152,7 @@ later how you can configure a service that has multiple instances in the
     In this example, the controller extends Symfony's base Controller, which
     gives you access to the service container itself. You can then use the
     ``get`` method to locate and retrieve the ``app.mailer`` service from
-    the service container. You can also define your :doc:`controllers as services </cookbook/controller/service>`.
-    This is a bit more advanced and not necessary, but it allows you to inject
-    only the services you need into your controller.
+    the service container.
 
 .. _book-service-container-parameters:
 

components/http_kernel/introduction.rst

@@ -264,9 +264,6 @@ will be called after another event - ``kernel.controller`` - is dispatched.
        is passed to it. This step is also specific to the  :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\ControllerResolver`
        sub-class used by the Symfony Framework.
 
-       There are also a few other variations on the above process (e.g. if
-       you're registering your controllers as services).
-
 .. _component-http-kernel-kernel-controller:
 
 3) The ``kernel.controller`` Event

cookbook/controller/service.rst

@@ -4,31 +4,40 @@
 How to Define Controllers as Services
 =====================================
 
+.. caution::
+
+    Defining controllers as services is **not officially recommended** by Symfony.
+    They are used by some developers for very specific use cases, such as
+    DDD (*domain-driven design*) and Hexagonal Architecture applications.
+
 In the book, you've learned how easily a controller can be used when it
 extends the base
 :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class. While
-this works fine, controllers can also be specified as services.
-
-.. note::
-
-    Specifying a controller as a service takes a bit more work. The
-    primary advantage is that the entire controller or any services passed to
-    the controller can be modified via the service container configuration.
-    This is especially useful when developing an open-source bundle or any
-    bundle that will be used in different projects.
-
-    A second advantage is that your controllers are more "sandboxed". By
-    looking at the constructor arguments, it's easy to see what types of things
-    this controller may or may not do. And because each dependency needs
-    to be injected manually, it's more obvious (i.e. if you have many constructor
-    arguments) when your controller is becoming too big. The recommendation from
-    the :doc:`best practices </best_practices/controllers>` is also valid for
-    controllers defined as services: Avoid putting your business logic into the
-    controllers. Instead, inject services that do the bulk of the work.
-
-    So, even if you don't specify your controllers as services, you'll likely
-    see this done in some open-source Symfony bundles. It's also important
-    to understand the pros and cons of both approaches.
+this works fine, controllers can also be specified as services. Even if you don't
+specify your controllers as services, you might see them being used in some
+open-source Symfony bundles, so it may be useful to understand both approaches.
+
+These are the main **advantages** of defining controllers as services:
+
+* The entire controller and any service passed to it can be modified via the
+  service container configuration. This is useful when developing reusable bundles;
+* Your controllers are more "sandboxed". By looking at the constructor arguments,
+  it's easy to see what types of things this controller may or may not do;
+* Since dependencies must be injected manually, it's more obvious when your
+  controller is becoming too big (i.e. if you have many constructor arguments).
+
+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;
+* 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
+logic into the controllers. Instead, inject services that do the bulk of the work.
 
 Defining the Controller as a Service
 ------------------------------------

create_framework/http_kernel_controller_resolver.rst

@@ -196,4 +196,3 @@ ever and it still has less than 40 lines of code.
 
 .. _`reflection`: http://php.net/reflection
 .. _`FrameworkExtraBundle`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
-.. _`controllers as services`: http://symfony.com/doc/current/cookbook/controller/service.html