-
-
Notifications
You must be signed in to change notification settings - Fork 5.2k
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.
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
Proofreading Javier's excellent updates - in some places, shortening some things #5304
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -27,7 +27,7 @@ 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 default error templates <use-default-exception-controller>`; | ||
the rest of your application, :ref:`override the default error templates <use-default-exception-controller>`; | ||
|
||
#. If you also want to tweak the logic used by Symfony to generate error pages, | ||
:ref:`override the default exception controller <custom-exception-controller>`; | ||
|
@@ -41,25 +41,16 @@ depending on your needs: | |
Overriding the Default Error Templates | ||
-------------------------------------- | ||
|
||
By default, the ``showAction()`` method of the | ||
:class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController` is called | ||
whenever an exception occurs, thanks to an event listener configured by the TwigBundle. | ||
|
||
Then, the controller selects one of the templates defined in the | ||
``Resources/views/Exception`` directory of the TwigBundle to render the error | ||
page. If you browse that directory (usually located in | ||
``vendor/symfony/symfony/src/Symfony/Bundle/TwigBundle``) you'll find a lot of | ||
templates defined for different types of errors and content formats | ||
(``error.*.twig`` templates are used in the production environment whereas | ||
``exception.*.twig`` templates are used in the development environment). | ||
When the error page loads, an internal :class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController` | ||
is used to render a Twig template to show the user. | ||
|
||
.. _cookbook-error-pages-by-status-code: | ||
|
||
The logic followed by the ``ExceptionController`` to pick one of the available | ||
templates is based on the HTTP status code and the request format: | ||
This controller uses the HTTP status code, request format 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.xml.twig``); | ||
or ``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 | ||
|
@@ -71,8 +62,29 @@ templates is based on the HTTP status code and the request format: | |
.. _overriding-or-adding-templates: | ||
|
||
To override these templates, simply rely on the standard Symfony method for | ||
:ref:`overriding templates that live inside a bundle <overriding-bundle-templates>`. | ||
For example, to override the 404 error template for HTML pages, create a new | ||
:ref:`overriding templates that live inside a bundle <overriding-bundle-templates>`: | ||
put them in the ``app/Resources/TwigBundle/views/Exception/`` directory. | ||
|
||
A typical project that returns HTML and JSON pages, might look like this: | ||
|
||
.. code-block:: text | ||
|
||
app/ | ||
├─ Resources/ | ||
│ └─ TwigBundle/ | ||
│ └─ views/ | ||
│ └─ 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) | ||
|
||
Example 404 Error Template | ||
-------------------------- | ||
|
||
To override the 404 error template for HTML pages, create a new | ||
``error404.html.twig`` template located at ``app/Resources/TwigBundle/views/Exception/``: | ||
|
||
.. code-block:: html+jinja | ||
|
@@ -83,16 +95,17 @@ For example, to override the 404 error template for HTML pages, create a new | |
{% block body %} | ||
<h1>Page not found</h1> | ||
|
||
{# example security usage, see below #} | ||
{% if app.user and is_granted('IS_AUTHENTICATED_FULLY') %} | ||
{# ... #} | ||
{% endif %} | ||
|
||
<p> | ||
The requested page couldn't be located. Checkout for any URL | ||
misspelling or <a href="{{ path('homepage') }}">return to the homepage</a>. | ||
</p> | ||
{% endblock %} | ||
|
||
Commonly, Symfony applications redefine the ``error404.html.twig`` template, the | ||
``error500.html.twig`` template for internal server errors and the generic | ||
``error.html.twig`` template to catch any other error different from 404 and 500. | ||
|
||
In case you need them, the ``ExceptionController`` passes some information to | ||
the error template via the ``status_code`` and ``status_text`` variables that | ||
store the HTTP status code and message respectively. | ||
|
@@ -132,14 +145,12 @@ is undefined. The solution is to add the following check before using this funct | |
Testing Error Pages during Development | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
One of the biggest hurdles of testing how do custom error pages look in your | ||
application is the fact that Symfony ignores them in the development environment | ||
and displays the default exception pages instead. | ||
Symfony shows the big *exception* page instead of your customized error page | ||
when you're in the development environem | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. environment. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Actually, with the paragraph below, we can just remove this one completely I guess. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. yep - good catch, that was my intention! |
||
|
||
You may be tempted to set the ``kernel.debug`` parameter to ``false`` to disable | ||
the debug mode in the development environment. However, this practice is not | ||
recommended because it will also stop Symfony from recompiling your Twig templates, | ||
among many other things. | ||
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? | ||
|
||
The recommended solution is to use a third-party bundle called `WebfactoryExceptionsBundle`_. | ||
This bundle provides a special test controller that allows you to easily display | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't it's usefull to show the line from
app/
, we don't do it for the sub dirs