minor #12687 Fix 12273 Added new ErrorController (dbrekelmans)

javiereguiluz · javiereguiluz · commit 891b677ef3f6 · 2019-12-09T12:54:57.000+01:00
This PR was squashed before being merged into the 4.4 branch (closes #12687). Discussion ---------- Fix 12273 Added new ErrorController Partially fixes #12273 The `Overriding the Default ErrorController` paragraph in `controller/error_pages.rst` still needs to be updated. I struggled with this so I would really appreciate if someone else could step in and finish that paragraph! For further reference, see #12273 (comment) Commits ------- 4c867f9 Fix 12273 Added new ErrorController
diff --git a/controller/error_pages.rst b/controller/error_pages.rst
@@ -9,14 +9,6 @@ In Symfony applications, all errors are treated as exceptions, no matter if they
 are just a 404 Not Found error or a fatal error triggered by throwing some
 exception in your code.
 
-If your app has the `TwigBundle`_ installed, a special controller handles these
-exceptions. This controller displays debug information for errors and allows to
-customize error pages, so run this command to make sure the bundle is installed:
-
-.. code-block:: terminal
-
-    $ composer require twig
-
 In the :ref:`development environment <configuration-environments>`,
 Symfony catches all the exceptions and displays a special **exception page**
 with lots of debug information to help you discover the root problem:
@@ -39,45 +31,50 @@ Error pages for the production environment can be customized in different ways
 depending on your needs:
 
 #. If you just want to change the contents and styles of the error pages to match
-   the rest of your application, :ref:`override the default error templates <use-default-exception-controller>`;
+   the rest of your application, :ref:`override the default error templates <use-default-error-controller>`;
+
+#. If you want to change the contents of non-HTML error output, :ref:`create a new normalizer <overriding-non-html-error-output>`;
 
 #. If you also want to tweak the logic used by Symfony to generate error pages,
-   :ref:`override the default exception controller <custom-exception-controller>`;
+   :ref:`override the default error controller <custom-error-controller>`;
 
 #. If you need total control of exception handling to execute your own logic
    :ref:`use the kernel.exception event <use-kernel-exception-event>`.
 
-.. _use-default-exception-controller:
-.. _using-the-default-exceptioncontroller:
+.. _use-default-error-controller:
+.. _using-the-default-errorcontroller:
 
 Overriding the Default Error Templates
 --------------------------------------
 
-When the error page loads, an internal :class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`
+You can use the built-in Twig error renderer to easily override the default error templates.
+Both the TwigBundle and TwigBridge need to be installed for this.
+Run this command to ensure both are installed:
+
+.. code-block:: terminal
+
+    $ composer require twig
+
+When the error page loads, :class:`Symfony\\Bridge\\Twig\\ErrorRenderer\\TwigErrorRenderer`
 is used to render a Twig template to show the user.
 
 .. _controller-error-pages-by-status-code:
 
-This controller uses the HTTP status code, the request format and the following
+This renderer uses the HTTP status code and the following
 logic to determine the template filename:
 
-#. Look for a template for the given format and status code (like ``error404.json.twig``
-   or ``error500.html.twig``);
+#. Look for a template for the given status code (like ``error500.html.twig``);
 
 #. If the previous template doesn't exist, discard the status code and look for
-   a generic template for the given format (like ``error.json.twig`` or
-   ``error.xml.twig``);
-
-#. If none of the previous templates exist, fall back to the generic HTML template
-   (``error.html.twig``).
+   a generic error template (``error.html.twig``).
 
 .. _overriding-or-adding-templates:
 
 To override these templates, rely on the standard Symfony method for
 :ref:`overriding templates that live inside a bundle <override-templates>` and
 put them in the ``templates/bundles/TwigBundle/Exception/`` directory.
 
-A typical project that returns HTML and JSON pages might look like this:
+A typical project that returns HTML pages might look like this:
 
 .. code-block:: text
 
@@ -87,10 +84,7 @@ A typical project that returns HTML and JSON pages might look like this:
           └─ Exception/
              ├─ error404.html.twig
              ├─ error403.html.twig
-             ├─ error.html.twig      # All other HTML errors (including 500)
-             ├─ error404.json.twig
-             ├─ error403.json.twig
-             └─ error.json.twig      # All other JSON errors (including 500)
+             └─ error.html.twig      # All other HTML errors (including 500)
 
 Example 404 Error Template
 --------------------------
@@ -112,24 +106,17 @@ To override the 404 error template for HTML pages, create a new
         </p>
     {% endblock %}
 
-In case you need them, the ``ExceptionController`` passes some information to
+In case you need them, the ``TwigErrorRenderer`` passes some information to
 the error template via the ``status_code`` and ``status_text`` variables that
 store the HTTP status code and message respectively.
 
 .. tip::
 
-    You can customize the status code by implementing
+    You can customize the status code of an exception by implementing
     :class:`Symfony\\Component\\HttpKernel\\Exception\\HttpExceptionInterface`
     and its required ``getStatusCode()`` method. Otherwise, the ``status_code``
     will default to ``500``.
 
-.. note::
-
-    The exception pages shown in the development environment can be customized
-    in the same way as error pages. Create a new ``exception.html.twig`` template
-    for the standard HTML exception page or ``exception.json.twig`` for the JSON
-    exception page.
-
 Security & 404 Pages
 --------------------
 
@@ -146,12 +133,12 @@ While you're in the development environment, Symfony shows the big *exception*
 page instead of your shiny new customized error page. So, how can you see
 what it looks like and debug it?
 
-Fortunately, the default ``ExceptionController`` allows you to preview your
+Fortunately, the default ``ErrorController`` allows you to preview your
 *error* pages during development.
 
-To use this feature, you need to load some special routes provided by TwigBundle
+To use this feature, you need to load some special routes provided by FrameworkBundle
 (if the application uses :ref:`Symfony Flex <symfony-flex>` they are loaded
-automatically when installing Twig support):
+automatically when installing ``symfony/framework-bundle``):
 
 .. configuration-block::
 
@@ -193,56 +180,88 @@ for a given status code as HTML or for a given status code and format.
      http://localhost/index.php/_error/{statusCode}
      http://localhost/index.php/_error/{statusCode}.{format}
 
-.. _custom-exception-controller:
-.. _replacing-the-default-exceptioncontroller:
+.. _overriding-non-html-error-output:
+
+Overriding Error output for non-HTML formats
+--------------------------------------------
 
-Overriding the Default ExceptionController
-------------------------------------------
+To override non-HTML error output, the Serializer component needs to be installed.
+
+.. code-block:: terminal
+
+    $ composer require serializer
+
+The Serializer component has a built-in ``FlattenException`` normalizer (``ProblemNormalizer``) and JSON/XML/CSV/YAML
+encoders by default. That means that if an exception were to be thrown in your application, Symfony can output it in
+a format supported by one of the encoders. If you want to change how the output is structured, all you have to do
+is create a new Normalizer that supports the ``FlattenException`` input::
+
+    class MyCustomProblemNormalizer implements NormalizerInterface
+    {
+        public function normalize($exception, $format = null, array $context = [])
+        {
+            return [
+                'content': 'This is my custom problem normalizer.',
+                'exception': [
+                    'message': $exception->getMessage(),
+                    'code': $exception->getStatusCode(),
+                ],
+            ];
+        }
+
+        public function supportsNormalization($data, $format = null)
+        {
+            return $data instanceof FlattenException;
+        }
+    }
+
+.. _custom-error-controller:
+.. _replacing-the-default-errorcontroller:
+
+Overriding the Default ErrorController
+--------------------------------------
 
 If you need a little more flexibility beyond just overriding the template,
 then you can change the controller that renders the error page. For example,
 you might need to pass some additional variables into your template.
 
 To do this, create a new controller anywhere in your application and set
-the :ref:`twig.exception_controller <config-twig-exception-controller>`
+the :ref:`framework.error_controller <config-framework-error_controller>`
 configuration option to point to it:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
-        # config/packages/twig.yaml
-        twig:
-            exception_controller: App\Controller\ExceptionController::showAction
+        # config/packages/framework.yaml
+        framework:
+            error_controller: App\Controller\ErrorController::showAction
 
     .. code-block:: xml
 
-        <!-- config/packages/twig.xml -->
+        <!-- config/packages/framework.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                https://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/twig
-                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
-            <twig:config>
-                <twig:exception-controller>App\Controller\ExceptionController::showAction</twig:exception-controller>
-            </twig:config>
+            <framework:config>
+                <framework:error_controller>App\Controller\ErrorController::showAction</framework:error_controller>
+            </framework:config>
 
         </container>
 
     .. code-block:: php
 
         // config/packages/twig.php
-        $container->loadFromExtension('twig', [
-            'exception_controller' => 'App\Controller\ExceptionController::showAction',
+        $container->loadFromExtension('framework', [
+            'error_controller' => 'App\Controller\ErrorController::showAction',
             // ...
         ]);
 
-The :class:`Symfony\\Component\\HttpKernel\\EventListener\\ExceptionListener`
-class used by the TwigBundle as a listener of the ``kernel.exception`` event creates
+The :class:`Symfony\\Component\\HttpKernel\\EventListener\\ErrorListener`
+class used by the FrameworkBundle as a listener of the ``kernel.exception`` event creates
 the request that will be dispatched to your controller. In addition, your controller
 will be passed two parameters:
 
@@ -355,5 +374,3 @@ time and again, you can have just one (or several) listeners deal with them.
     your application (like :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`)
     and takes measures like redirecting the user to the login page, logging them
     out and other things.
-
-.. _`TwigBundle`: https://github.com/symfony/twig-bundle
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -74,6 +74,7 @@ Configuration
 
 * `default_locale`_
 * `disallow_search_engine_index`_
+* `error_controller`_
 * `esi`_
 
   * :ref:`enabled <reference-esi-enabled>`
@@ -596,6 +597,23 @@ If you're using forms, but want to avoid starting your session (e.g. using
 forms in an API-only website), ``csrf_protection`` will need to be set to
 ``false``.
 
+.. _config-framework-error_controller:
+
+error_controller
+~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``error_controller``
+
+.. versionadded:: 4.4
+
+    The ``error_controller`` option was introduced in Symfony 4.4.
+
+This is the controller that is activated after an exception is thrown anywhere
+in your application. The default controller
+(:class:`Symfony\\Component\\HttpKernel\\Controller\\ErrorController`)
+is what's responsible for rendering specific templates under different error
+conditions (see :doc:`/controller/error_pages`).
+
 esi
 ~~~
 
diff --git a/reference/configuration/twig.rst b/reference/configuration/twig.rst
@@ -203,6 +203,12 @@ exception_controller
 
 **type**: ``string`` **default**: ``twig.controller.exception:showAction``
 
+.. deprecated:: 4.4
+
+    The ``exception_controller`` configuration option was deprecated in Symfony 4.4.
+    Set it to ``null`` and use the new ``error_controller`` option under ``framework``
+    configuration instead.
+
 This is the controller that is activated after an exception is thrown anywhere
 in your application. The default controller
 (:class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`)
