How to Customize Error Pages

Overriding the Default Error Templates

When the error page loads, an internal ExceptionController is used to render a Twig template to show the user.

This controller uses the HTTP status code, the request format and the following logic to determine the template filename:

1. Look for a template for the given format and status code (like error404.json.twig or error500.html.twig);
2. 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 error.xml.twig);
3. If none of the previous template exist, fall back to the generic HTML template (error.html.twig).

To override these templates, simply rely on the standard Symfony method for overriding templates that live inside a bundle: put them in the app/Resources/TwigBundle/views/Exception/ directory.

A typical project that returns HTML and JSON pages, might look like this:

1
2
3
4
5
6
7
8
9
10
11

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/:

1
2
3
4
5
6
7
8
9
10
11

{# app/Resources/TwigBundle/views/Exception/error404.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
    <h1>Page not found</h1>

    <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 %}

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.

1
2
3
4

# app/config/routing_dev.yml
_errors:
    resource: "@TwigBundle/Resources/config/routing/errors.xml"
    prefix:   /_error

1
2
3
4
5
6
7
8
9
10

<!-- 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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="@TwigBundle/Resources/config/routing/errors.xml"
        prefix="/_error"/>
</routes>

1
2
3
4
5
6
7
8
9
10

// app/config/routing_dev.php
use Symfony\Component\Routing\RouteCollection;

$routes = new RouteCollection();
$routes->addCollection(
    $loader->import('@TwigBundle/Resources/config/routing/errors.xml')
);
$routes->addPrefix("/_error");

return $routes;

1
2

http://localhost/app_dev.php/_error/{statusCode}
http://localhost/app_dev.php/_error/{statusCode}.{format}

Overriding the Default ExceptionController

If you need a little more flexibility beyond just overriding the template, then you can change the controller that renders the error page. For example, you might need to pass some additional variables into your template.

To do this, simply create a new controller anywhere in your application and set the twig.exception_controller configuration option to point to it:

1
2
3

# app/config/config.yml
twig:
    exception_controller: AppBundle:Exception:showAction

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="http://symfony.com/schema/dic/twig"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/twig
        https://symfony.com/schema/dic/twig/twig-1.0.xsd">

    <twig:config>
        <twig:exception-controller>AppBundle:Exception:showAction</twig:exception-controller>
    </twig:config>

</container>

1
2
3
4
5

// app/config/config.php
$container->loadFromExtension('twig', [
    'exception_controller' => 'AppBundle:Exception:showAction',
    // ...
]);

The ExceptionListener class used by the TwigBundle as a listener of the kernel.exception event creates the request that will be dispatched to your controller. In addition, your controller will be passed two parameters:

exception

A FlattenException instance created from the exception being handled.

logger

A DebugLoggerInterface instance which may be null in some circumstances.

Instead of creating a new exception controller from scratch you can also extend the default ExceptionController. In that case, you might want to override one or both of the showAction() and findTemplate() methods. The latter one locates the template to be used.

1
2
3
4
5
6
7
8
9
10
11

# app/config/services.yml
services:
    _defaults:
        # ... be sure autowiring is enabled
        autowire: true
    # ...

    AppBundle\Controller\CustomExceptionController:
        public: true
        arguments:
            $debug: '%kernel.debug%'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<!-- app/config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <!-- ... be sure autowiring is enabled -->
        <defaults autowire="true"/>
        <!-- ... -->

        <service id="AppBundle\Controller\CustomExceptionController" public="true">
            <argument key="$debug">%kernel.debug%</argument>
        </service>
    </services>

</container>

1
2
3
4
5

// app/config/services.php
use AppBundle\Controller\CustomExceptionController;

$container->autowire(CustomExceptionController::class)
    ->setArgument('$debug', '%kernel.debug%');

Working with the kernel.exception Event

When an exception is thrown, the HttpKernel class catches it and dispatches a kernel.exception event. This gives you the power to convert the exception into a Response in a few different ways.

Working with this event is actually much more powerful than what has been explained before, but also requires a thorough understanding of Symfony internals. Suppose that your code throws specialized exceptions with a particular meaning to your application domain.

Writing your own event listener for the kernel.exception event allows you to have a closer look at the exception and take different actions depending on it. Those actions might include logging the exception, redirecting the user to another page or rendering specialized error pages.

This approach allows you to create centralized and layered error handling: instead of catching (and handling) the same exceptions in various controllers time and again, you can have just one (or several) listeners deal with them.