Cover of the book Symfony 5: The Fast Track

Symfony 5: The Fast Track is the best book to learn modern Symfony development, from zero to production. +300 pages in full color showing how to combine Symfony with Docker, APIs, queues & async tasks, Webpack, Single-Page Applications, etc.

Buy printed version

New in Symfony 4.4: ErrorHandler Component

Contributed by
Yonel Ceruto
in #31065.

The Debug component was released in 2013 to provide three important features to Symfony applications:

  • A debugging class loader to throw helpful exceptions when some class wasn't found;
  • An error handler to catch PHP errors and convert them into exceptions;
  • An exception handler to catch uncaught PHP exceptions and display nice error pages for them.

You just had to add Debug::enable(); in your code (for example in the front controller when the debug kernel option was set) to enable all these features that improve your development experience.

In Symfony 4.4 we've introduced a new component called ErrorHandler which replaces the Debug component and provides the same features in a more modern and powerful way.

The main issue of the previous DebugBundle is that you needed to install the TwigBundle too in order to 1) get exceptions in the same non-HTML format of the request and 2) get the advanced HTML error pages. This was not only cumbersome but also confusing for API-only applications that don't use Twig.

The new ErrorHandler component always generates exceptions in the same format as the request and it doesn't require using Twig. This introduces some changes which are explained in the Symfony 4.4 UPGRADE guide.

The most important change is that you can no longer customize error pages for non-HTML formats using Twig templates (e.g. templates/bundles/TwigBundle/Exception/error403.json.twig). When the request format is JSON, XML, ATOM or TXT, exception pages follow the RFC 7807 standard and have the following structure (the following example only shows the JSON structure):

1
2
3
4
5
{
    "title": "Not Found",
    "status": 404,
    "detail": "Sorry, the page you are looking for could not be found"
}

If you want to override this content, you must add the Serializer component to your project and create a custom normalizer as explained in the docs.

The other important change is related to the error page preview feature. Although this feature keeps working as before, some files have changed their location, so you need to make the following changes in your project configuration:

1
2
3
4
5
6
- # config/routes/dev/twig.yaml
+ # config/routes/dev/framework.yaml
_errors:
-     resource: '@TwigBundle/Resources/config/routing/errors.xml'
+     resource: '@FrameworkBundle/Resources/config/routing/errors.xml'
    prefix:   /_error

In summary, the new ErrorHandler component keeps all the great features of the Debug component but removes the Twig dependency and makes Symfony exceptions compliant with modern standards.

Help the Symfony project!

As with any Open-Source project, contributing code or documentation is the most common way to help, but we also have a wide range of sponsoring opportunities.

Comments

Thank you :')
Really good, thank's !
"If you want to override this content" defining your own error controller will be the last option.

It's recommended require symfony/serializer and create a new normalizer class as explained here https://symfony.com/doc/current/controller/error_pages.html#overriding-error-output-for-non-html-formats
@Yonel thanks for reporting this problem. I've just updated the blog post to mention what you said. Thanks!
Thank you Yonel 😃
I'm confused. How do I update my project to use it? Do I need to remove the debug-bundle or rather debug-pack? Do I need to make some changes in my code?
I've already updated my app to symfony 4.4. I've also removed FOSRestBundle, and would now expect a request with `Accept: application/json` header to give a proper json error (upon HttpException), but instead I get a HTML page (both on env=dev and env=prod). Is there anything I need to configure? I've updated the twig error page and have no custom controller, templates or serializer.. just expecting the default behavior. What's wrong?
@ReinBaarsma you will need to install/enable the serializer component, that's all. If it still doesn't work for you, please create an issue + reproducer app to discuss it. Thanks!

Comments are closed.

To ensure that comments stay relevant, they are closed for old posts.