diff --git a/book/controller.rst b/book/controller.rst index 418fa173f3c..ff83bd46b95 100644 --- a/book/controller.rst +++ b/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 `. - This is optional, but can give you more control over the exact - objects/dependencies that are injected into your controller. - .. index:: single: Controller; Redirecting diff --git a/book/page_creation.rst b/book/page_creation.rst index ce3be3ce65b..c8ef4f70bf2 100644 --- a/book/page_creation.rst +++ b/book/page_creation.rst @@ -347,11 +347,6 @@ also get a lot of shortcut methods, like ``render()``:: Learn more about these shortcut methods and how they work in the :doc:`Controller ` chapter. -.. tip:: - - For more advanced users, you can also - :doc:`register your controllers as services `. - Create the Template ~~~~~~~~~~~~~~~~~~~ diff --git a/book/service_container.rst b/book/service_container.rst index 828ff40104d..573ddbcfaca 100644 --- a/book/service_container.rst +++ b/book/service_container.rst @@ -186,9 +186,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 `. - 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: diff --git a/components/http_kernel/introduction.rst b/components/http_kernel/introduction.rst index 1a808980b5e..4b96ae58395 100644 --- a/components/http_kernel/introduction.rst +++ b/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 diff --git a/cookbook/controller/service.rst b/cookbook/controller/service.rst index d4bb24c68d5..501e2c99fb4 100644 --- a/cookbook/controller/service.rst +++ b/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 ` 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 ` +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 ------------------------------------ diff --git a/create_framework/http_kernel_controller_resolver.rst b/create_framework/http_kernel_controller_resolver.rst index c0cf260cf0b..b8fd79596db 100644 --- a/create_framework/http_kernel_controller_resolver.rst +++ b/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