From cf2ae91144668d0de968e11fd766a0557b26946a Mon Sep 17 00:00:00 2001 From: Guilhem Niot Date: Sun, 19 Mar 2017 16:21:05 +0100 Subject: [PATCH 1/3] [FrameworkBundle] Document the AbstractController --- controller.rst | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/controller.rst b/controller.rst index 3ef67d063d7..98626ca9857 100644 --- a/controller.rst +++ b/controller.rst @@ -116,19 +116,26 @@ For more information on routing, see :doc:`/routing`. .. index:: single: Controller; Base controller class -The Base Controller Class & Services ------------------------------------- +The Base Controller Classes & Services +-------------------------------------- -For convenience, Symfony comes with an optional base -:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class. -If you extend it, this won't change anything about how your controller -works, but you'll get access to a number of **helper methods** and the -**service container** (see :ref:`controller-accessing-services`): an +For convenience, Symfony comes with two optional base +:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` and +:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController` +classes. +If you extend one or the other, this won't change anything about how your +controller works, but you'll get access to a number of **helper methods**. + +The base ``Controller`` also allows you to access the **service container** (see :ref:`controller-accessing-services`): an array-like object that gives you access to every useful object in the system. These useful objects are called **services**, and Symfony ships with a service object that can render Twig templates, another that can log messages and many more. +On the other hand, the ``AbstractController`` prevents you from accessing the +**service container**. This forces you to write a code more robust by +forcing you to explicitly define your dependencies. + Add the ``use`` statement atop the ``Controller`` class and then modify ``LuckyController`` to extend it:: @@ -144,7 +151,7 @@ Add the ``use`` statement atop the ``Controller`` class and then modify Helper methods are just shortcuts to using core Symfony functionality that's available to you with or without the use of the base -``Controller`` class. A great way to see the core functionality in +controller classes. A great way to see the core functionality in action is to look in the :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class. @@ -241,10 +248,9 @@ are used for rendering templates, sending emails, querying the database and any other "work" you can think of. When you install a new bundle, it probably brings in even *more* services. -When extending the base controller class, you can access any Symfony service +When extending the base ``Controller`` class, you can access any Symfony service via the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::get` -method of the ``Controller`` class. Here are several common services you might -need:: +method. Here are several common services you might need:: $templating = $this->get('templating'); @@ -279,7 +285,8 @@ Managing Errors and 404 Pages When things are not found, you should play well with the HTTP protocol and return a 404 response. To do this, you'll throw a special type of exception. -If you're extending the base ``Controller`` class, do the following:: +If you're extending the base ``Controller`` or the base ``AbstractController`` +class, do the following:: public function indexAction() { From 88a4806dcda558849e88b01b32dfe792a53dc8df Mon Sep 17 00:00:00 2001 From: Guilhem Niot Date: Thu, 6 Apr 2017 17:34:26 +0200 Subject: [PATCH 2/3] Fix --- controller.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/controller.rst b/controller.rst index 98626ca9857..55b49b60ac2 100644 --- a/controller.rst +++ b/controller.rst @@ -116,6 +116,9 @@ For more information on routing, see :doc:`/routing`. .. index:: single: Controller; Base controller class +.. _anchor-name: +:ref:`The Base Controller Classes & Services ` + The Base Controller Classes & Services -------------------------------------- From 4ac5da7898af93ee9a79cf6574a6a7e3c7756c00 Mon Sep 17 00:00:00 2001 From: Guilhem Niot Date: Fri, 7 Apr 2017 17:28:17 +0200 Subject: [PATCH 3/3] Fix --- controller.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/controller.rst b/controller.rst index 55b49b60ac2..65bb450bb89 100644 --- a/controller.rst +++ b/controller.rst @@ -117,7 +117,7 @@ For more information on routing, see :doc:`/routing`. single: Controller; Base controller class .. _anchor-name: -:ref:`The Base Controller Classes & Services ` + :ref:`The Base Controller Classes & Services ` The Base Controller Classes & Services -------------------------------------- @@ -136,8 +136,9 @@ with a service object that can render Twig templates, another that can log messages and many more. On the other hand, the ``AbstractController`` prevents you from accessing the -**service container**. This forces you to write a code more robust by -forcing you to explicitly define your dependencies. +**service container**. When you need an external dependency, this forces you to +write a code more robust as you have to explicitly define your dependencies by +using :doc:`the controller as a service `. Add the ``use`` statement atop the ``Controller`` class and then modify ``LuckyController`` to extend it::