Permalink
Browse files

feature #4293 Document error page preview (Symfony ~2.6) (mpdude)

This PR was merged into the master branch.

Discussion
----------

Document error page preview (Symfony ~2.6)

This adds documentation how to use the new preview feature from symfony/symfony#12096 (and hopefully the fix in symfony/symfony#12147).

Commits
-------

d02c7c4 Updates according to GH feedback
8e70373 Document error page preview in Symfony ~2.6 (#4293)
  • Loading branch information...
weaverryan committed Oct 19, 2014
2 parents 142c826 + d02c7c4 commit 2cd6646eac53b88ccf4ee2e2834ed82dcae66ef2
Showing with 74 additions and 11 deletions.
  1. +74 −11 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.
.. tip::
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``.
.. _`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,70 @@ 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
.. code-block:: xml
<!-- app/config/routing_dev.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/routing
http://symfony.com/schema/routing/routing-1.0.xsd">
<import resource="@TwigBundle/Resources/config/routing/errors.xml"
prefix="/_error" />
</routes>
.. 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.
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.
.. _custom-exception-controller:
Replacing the Default ExceptionController
@@ -235,6 +291,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
@@ -285,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

0 comments on commit 2cd6646

Please sign in to comment.