Symfony News

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 define your own error controller and use it as the value of the new framework.error_controller config option.

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.