Skip to content

Document error page preview (Symfony ~2.6) #4293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 19, 2014
Merged

Document error page preview (Symfony ~2.6) #4293

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8e70373
Document error page preview in Symfony ~2.6 (#4293)
mpdude Oct 17, 2014
d02c7c4
Updates according to GH feedback
mpdude Oct 19, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 74 additions & 11 deletions cookbook/controller/error_pages.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems a little silly here, but we always show the XML and PHP formats as well. Could you add those? Check the routing chapter of the book for examples.


.. 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")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This path looks like it's suffering from some copy and paste :). But that's so minor I'll fix it in a moment.

);
$collection->addPrefix("/error");

return $collection;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not try to use/run the .xml and .php variant, please have a look at it and make sure it's correct.


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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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