From 8e7037357082048a5d754e6004e5b0f36df6570b Mon Sep 17 00:00:00 2001 From: Matthias Pigulla Date: Fri, 17 Oct 2014 23:48:17 +0200 Subject: [PATCH 1/2] Document error page preview in Symfony ~2.6 (#4293) Feature added in symfony/symfony#12096. --- cookbook/controller/error_pages.rst | 66 ++++++++++++++++++++++++----- 1 file changed, 55 insertions(+), 11 deletions(-) diff --git a/cookbook/controller/error_pages.rst b/cookbook/controller/error_pages.rst index fa8efef21fc..b087bd69fab 100644 --- a/cookbook/controller/error_pages.rst +++ b/cookbook/controller/error_pages.rst @@ -42,18 +42,10 @@ flag. While *exception* pages give you a lot of helpful information during development, *error* pages are meant to be shown to the user in production. -.. sidebar:: Testing Error Pages during Development - - You should not set ``kernel.debug`` to ``false`` in order to see your - *error* pages during development. This will also stop - Symfony from recompiling your twig templates, among other things. - - The third-party `WebfactoryExceptionsBundle`_ provides a special - test controller that allows you to display your custom error - pages for arbitrary HTTP status codes even with - ``kernel.debug`` set to ``true``. +.. tip:: -.. _`WebfactoryExceptionsBundle`: https://github.com/webfactory/exceptions-bundle + You can also :ref:`preview your error pages ` + in ``kernel.debug`` mode. .. _cookbook-error-pages-by-status-code: @@ -153,6 +145,53 @@ Refer to the previous section for the order in which the ``exception.html.twig`` for the standard HTML exception page or ``exception.json.twig`` for the JSON exception page. +.. _testing-error-pages: + +Testing Error Pages during Development +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The default ``ExceptionController`` also allows you to preview your +*error* pages during development. + +.. versionadded:: 2.6 + This feature was introduced in Symfony 2.6. Before, the third-party + `WebfactoryExceptionsBundle`_ could be used for the same purpose. + +To use this feature, you need to have a definition in your +``routing_dev.yml`` file like so: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/routing_dev.yml + _errors: + resource: "@TwigBundle/Resources/config/routing/errors.xml" + prefix: /_error + +If you're coming from an older version of Symfony, you might need to +add this to your ``routing_dev.yml`` file. If you're starting from +scratch, the `Symfony Standard Edition`_ already contains it for you. + +With this route added, you can use URLs like + +.. code-block:: text + + http://localhost/app_dev.php/_error/{statusCode} + http://localhost/app_dev.php/_error/{statusCode}.{format} + +to preview the *error* page for a given status code as HTML or for a +given status code and format. + +.. tip:: + + You should not set ``kernel.debug`` to ``false`` in order to see your + error pages during development. This will also stop + Symfony from recompiling your twig templates, among other things. + +.. _`WebfactoryExceptionsBundle`: https://github.com/webfactory/exceptions-bundle +.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard/ + .. _custom-exception-controller: Replacing the Default ExceptionController @@ -235,6 +274,11 @@ template to be used. As of writing, the ``ExceptionController`` is *not* part of the Symfony API, so be aware that it might change in following releases. +.. tip:: + + The :ref:`error page preview ` also works for + your own controllers set up this way. + .. _use-kernel-exception-event: Working with the kernel.exception Event From d02c7c4663b82bd34683be828b0f12f74de88e5f Mon Sep 17 00:00:00 2001 From: Matthias Pigulla Date: Sun, 19 Oct 2014 22:59:02 +0200 Subject: [PATCH 2/2] Updates according to GH feedback --- cookbook/controller/error_pages.rst | 37 ++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/cookbook/controller/error_pages.rst b/cookbook/controller/error_pages.rst index b087bd69fab..83b8c0b4d0d 100644 --- a/cookbook/controller/error_pages.rst +++ b/cookbook/controller/error_pages.rst @@ -169,6 +169,32 @@ To use this feature, you need to have a definition in your resource: "@TwigBundle/Resources/config/routing/errors.xml" prefix: /_error + .. code-block:: xml + + + + + + + + + .. code-block:: php + + // app/config/routing_dev.php + use Symfony\Component\Routing\RouteCollection; + + $collection = new RouteCollection(); + $collection->addCollection( + $loader->import("@AcmeHelloBundle/Resources/config/routing.php") + ); + $collection->addPrefix("/error"); + + return $collection; + If you're coming from an older version of Symfony, you might need to add this to your ``routing_dev.yml`` file. If you're starting from scratch, the `Symfony Standard Edition`_ already contains it for you. @@ -183,15 +209,6 @@ With this route added, you can use URLs like to preview the *error* page for a given status code as HTML or for a given status code and format. -.. tip:: - - You should not set ``kernel.debug`` to ``false`` in order to see your - error pages during development. This will also stop - Symfony from recompiling your twig templates, among other things. - -.. _`WebfactoryExceptionsBundle`: https://github.com/webfactory/exceptions-bundle -.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard/ - .. _custom-exception-controller: Replacing the Default ExceptionController @@ -329,4 +346,6 @@ several) listeners deal with them. Good luck! +.. _`WebfactoryExceptionsBundle`: https://github.com/webfactory/exceptions-bundle +.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard/ .. _`ExceptionListener`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Security/Http/Firewall/ExceptionListener.php