English spoken conference

You are browsing the Symfony 5.0 documentation, which changes significantly from Symfony 3.x. If your app doesn't use Symfony 5.0 yet, browse the Symfony 3.4 documentation.

The ErrorRenderer Component

5.0 version
Maintained

The ErrorRenderer Component

The ErrorRenderer component converts PHP errors and exceptions into other formats such as JSON and HTML and renders them.

Installation

1
$ composer require symfony/error-renderer

Note

If you install this component outside of a Symfony application, you must require the vendor/autoload.php file in your code to enable the class autoloading mechanism provided by Composer. Read this article for more details.

Usage

The ErrorRenderer component provides several renderers to convert PHP errors and exceptions into other formats such as JSON and HTML easier to debug when working with HTTP applications:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
use Symfony\Component\ErrorRenderer\ErrorRenderer;
use Symfony\Component\ErrorRenderer\ErrorRenderer\HtmlErrorRenderer;
use Symfony\Component\ErrorRenderer\ErrorRenderer\JsonErrorRenderer;
use Symfony\Component\ErrorRenderer\Exception\FlattenException;
use Symfony\Component\HttpFoundation\Response;

$renderers = [
    new HtmlErrorRenderer(),
    new JsonErrorRenderer(),
    // ...
];
$errorRenderer = new ErrorRenderer($renderers);

try {
    // ...
} catch (\Throwable $e) {
    $e = FlattenException::createFromThrowable($e);

    return new Response($errorRenderer->render($e, 'json'), 500, ['Content-Type' => 'application/json']);
}

Built-in Error Renderers

This component provides error renderers for the most common needs:

Adding a Custom Error Renderer

Error renderers are PHP classes that implement the ErrorRendererInterface. For example, if you need to render errors in JSON-LD format, create this class anywhere in your project:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
namespace App\ErrorRenderer;

use Symfony\Component\ErrorRenderer\ErrorRenderer\ErrorRendererInterface;
use Symfony\Component\ErrorRenderer\Exception\FlattenException;

class JsonLdErrorRenderer implements ErrorRendererInterface
{
    private $debug;

    public function __construct(bool $debug = true)
    {
        $this->debug = $debug;
    }

    public static function getFormat(): string
    {
        return 'jsonld';
    }

    public function render(FlattenException $exception): string
    {
        $content = [
            '@id' => 'https://example.com',
            '@type' => 'error',
            '@context' => [
                'title' => $exception->getTitle(),
                'code' => $exception->getStatusCode(),
                'message' => $exception->getMessage(),
            ],
        ];

        if ($this->debug) {
            $content['@context']['exceptions'] = $exception->toArray();
        }

        return (string) json_encode($content);
    }
}

Tip

If the getFormat() method of your error renderer matches one of formats supported by the built-in renderers, the built-in renderer is replaced by your custom renderer.

To enable the new error renderer in the application, register it as a service and tag it with the error_renderer.renderer tag.

  • YAML
    1
    2
    3
    4
    5
    # config/services.yaml
    services:
        App\ErrorRenderer\JsonLdErrorRenderer:
            arguments: ['%kernel.debug%']
            tags: ['error_renderer.renderer']
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    <!-- 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>
            <service id="App\ErrorRenderer\JsonLdErrorRenderer">
                <argument>%kernel.debug%</argument>
                <tag name="error_renderer.renderer"/>
            </service>
        </services>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    // config/services.php
    use App\ErrorRenderer\JsonLdErrorRenderer;
    
    $container->register(JsonLdErrorRenderer::class)
        ->setArguments([$container->getParameter('kernel.debug')]);
        ->addTag('error_renderer.renderer');
    

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.