Document error page preview in Symfony ~2.6 (#4293)

mpdude · mpdude · commit 8e7037357082 · 2014-10-17T23:48:17.000+02:00
Feature added in symfony/symfony#12096.
diff --git 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 <testing-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 <testing-error-pages>` also works for
+    your own controllers set up this way.
+
 .. _use-kernel-exception-event:
 
 Working with the kernel.exception Event
