Skip to content

Commit b2a1a9b

Browse files
javiereguiluzyceruto
javiereguiluz
authored and
yceruto
committed
Documented the ErrorCatcher component
1 parent def3df3 commit b2a1a9b

File tree

4 files changed

+214
-41
lines changed

4 files changed

+214
-41
lines changed

‎components/debug.rst

Lines changed: 5 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Installation
1212

1313
.. code-block:: terminal
1414
15-
$ composer require symfony/debug
15+
$ composer require --dev symfony/debug
1616
1717
.. include:: /components/require_autoload.rst.inc
1818

@@ -26,50 +26,16 @@ Enable all of them by calling this method::
2626

2727
Debug::enable();
2828

29-
The :method:`Symfony\\Component\\Debug\\Debug::enable` method registers an
30-
error handler, an exception handler and
31-
:ref:`a special class loader <component-debug-class-loader>`.
32-
33-
Read the following sections for more information about the different available
34-
tools.
35-
3629
.. caution::
3730

3831
You should never enable the debug tools, except for the error handler, in a
3932
production environment as they might disclose sensitive information to the user.
4033

41-
Enabling the Error Handler
42-
--------------------------
43-
44-
The :class:`Symfony\\Component\\Debug\\ErrorHandler` class catches PHP errors
45-
and converts them to exceptions (of class :phpclass:`ErrorException` or
46-
:class:`Symfony\\Component\\Debug\\Exception\\FatalErrorException` for PHP
47-
fatal errors)::
48-
49-
use Symfony\Component\Debug\ErrorHandler;
50-
51-
ErrorHandler::register();
52-
53-
This error handler is enabled by default in the production environment when the
54-
application uses the FrameworkBundle because it generates better error logs.
55-
56-
Enabling the Exception Handler
57-
------------------------------
58-
59-
The :class:`Symfony\\Component\\Debug\\ExceptionHandler` class catches
60-
uncaught PHP exceptions and converts them to a nice PHP response. It is useful
61-
in debug mode to replace the default PHP/XDebug output with something prettier
62-
and more useful::
63-
64-
use Symfony\Component\Debug\ExceptionHandler;
65-
66-
ExceptionHandler::register();
67-
68-
.. note::
34+
.. deprecated:: 4.4
6935

70-
If the :doc:`HttpFoundation component </components/http_foundation>` is
71-
available, the handler uses a Symfony Response object; if not, it falls
72-
back to a regular PHP response.
36+
In Symfony versions before 4.4, this component also provided error and
37+
exception handlers. In Symfony 4.4 they were deprecated in favor of their
38+
equivalent handlers included in the new :doc:`ErrorCatcher component </components/error_catcher>`.
7339

7440
.. _component-debug-class-loader:
7541

‎components/error_catcher.rst

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
.. index::
2+
single: Error
3+
single: Exception
4+
single: Components; ErrorCatcher
5+
6+
The ErrorCatcher Component
7+
==========================
8+
9+
The ErrorCatcher component converts PHP errors and exceptions into other
10+
formats such as JSON and HTML and renders them.
11+
12+
Installation
13+
------------
14+
15+
.. code-block:: terminal
16+
17+
$ composer require symfony/error-catcher
18+
19+
.. include:: /components/require_autoload.rst.inc
20+
21+
Usage
22+
-----
23+
24+
The ErrorCatcher component provides several handlers and renderers to convert
25+
PHP errors and exceptions into other formats easier to debug when working with
26+
HTTP applications.
27+
28+
.. TODO: how are these handlers enabled in the app? (Previously: Debug::enable())
29+
30+
Handling PHP Errors and Exceptions
31+
----------------------------------
32+
33+
Enabling the Error Handler
34+
~~~~~~~~~~~~~~~~~~~~~~~~~~
35+
36+
The :class:`Symfony\\Component\\ErrorCatcher\\ErrorHandler` class catches PHP
37+
errors and converts them to exceptions (of class :phpclass:`ErrorException` or
38+
:class:`Symfony\\Component\\ErrorCatcher\\Exception\\FatalErrorException` for
39+
PHP fatal errors)::
40+
41+
use Symfony\Component\ErrorCatcher\ErrorHandler;
42+
43+
ErrorHandler::register();
44+
45+
This error handler is enabled by default in the production environment when the
46+
application uses the FrameworkBundle because it generates better error logs.
47+
48+
Enabling the Exception Handler
49+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
50+
51+
The :class:`Symfony\\Component\\ErrorCatcher\\ExceptionHandler` class catches
52+
uncaught PHP exceptions and converts them to a nice PHP response. It is useful
53+
in :ref:`debug mode <debug-mode>` to replace the default PHP/XDebug output with
54+
something prettier and more useful::
55+
56+
use Symfony\Component\ErrorCatcher\ExceptionHandler;
57+
58+
ExceptionHandler::register();
59+
60+
.. note::
61+
62+
If the :doc:`HttpFoundation component </components/http_foundation>` is
63+
available, the handler uses a Symfony Response object; if not, it falls
64+
back to a regular PHP response.
65+
66+
Rendering PHP Errors and Exceptions
67+
-----------------------------------
68+
69+
Another feature provided by this component are the "error renderers", which
70+
converts PHP errors and exceptions into other formats such as JSON and HTML::
71+
72+
use Symfony\Component\ErrorHandler\ErrorRenderer\ErrorRenderer;
73+
use Symfony\Component\ErrorHandler\ErrorRenderer\HtmlErrorRenderer;
74+
use Symfony\Component\ErrorHandler\ErrorRenderer\JsonErrorRenderer;
75+
76+
$renderers = [
77+
new HtmlErrorRenderer(),
78+
new JsonErrorRenderer(),
79+
// ...
80+
];
81+
$errorRenderer = new ErrorRenderer($renderers);
82+
83+
/** @var Symfony\Component\ErrorHandler\Exception\FlattenException */
84+
$exception = ...;
85+
/** @var Symfony\Component\HttpFoundation\Request */
86+
$request = ...;
87+
88+
return new Response(
89+
$errorRenderer->render($exception, $request->getRequestFormat()),
90+
$exception->getStatusCode(),
91+
$exception->getHeaders()
92+
);
93+
94+
Built-in Error Renderers
95+
~~~~~~~~~~~~~~~~~~~~~~~~
96+
97+
This component provides error renderers for the most common needs:
98+
99+
* :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\HtmlErrorRenderer`
100+
renders errors in HTML format;
101+
* :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\JsonErrorRenderer`
102+
renders errors in JsonErrorRenderer format and it's compliant with the
103+
`RFC 7807`_ standard;
104+
* :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\XmlErrorRenderer`
105+
renders errors in XML and Atom formats. It's compliant with the `RFC 7807`_
106+
standard;
107+
* :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\TxtErrorRenderer`
108+
renders errors in regular text format.
109+
110+
Adding a Custom Error Renderer
111+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112+
113+
Error renderers are PHP classes that implement the
114+
:class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\ErrorRendererInterface`.
115+
For example, if you need to render errors in `JSON-LD format`_, create this
116+
class anywhere in your project::
117+
118+
namespace App\ErrorHandler\ErrorRenderer;
119+
120+
use Symfony\Component\ErrorHandler\ErrorRenderer\ErrorRendererInterface;
121+
use Symfony\Component\ErrorHandler\Exception\FlattenException;
122+
123+
class JsonLdErrorRenderer implements ErrorRendererInterface
124+
{
125+
private $debug;
126+
127+
public static function getFormat(): string
128+
{
129+
return 'jsonld';
130+
}
131+
132+
public function __construct(bool $debug = true)
133+
{
134+
$this->debug = $debug;
135+
}
136+
137+
public function render(FlattenException $exception): string
138+
{
139+
$content = [
140+
'@id' => 'https://example.com',
141+
'@type' => 'error',
142+
'@context' => [
143+
'title' => $exception->getTitle(),
144+
'code' => $exception->getStatusCode(),
145+
'message' => $exception->getMessage(),
146+
],
147+
];
148+
149+
if ($this->debug) {
150+
$content['@context']['exceptions'] = $exception->toArray();
151+
}
152+
153+
return (string) json_encode($content);
154+
}
155+
}
156+
157+
.. tip::
158+
159+
If the ``getformat()`` method of your error renderer matches one of formats
160+
supported by the built-in renderers, the built-in renderer is replaced by
161+
your custom renderer.
162+
163+
To enable the new error renderer in the application,
164+
:ref:`register it as a service <service-container-creating-service>` and
165+
:doc:`tag it </service_container/tags>` with the ``error_handler.renderer``
166+
tag.
167+
168+
.. configuration-block::
169+
170+
.. code-block:: yaml
171+
172+
# config/services.yaml
173+
services:
174+
App\ErrorHandler\ErrorRenderer\JsonLdErrorRenderer:
175+
arguments: ['%kernel.debug%']
176+
tags: ['error_handler.renderer']
177+
178+
.. code-block:: xml
179+
180+
<!-- config/services.xml -->
181+
<?xml version="1.0" encoding="UTF-8" ?>
182+
<container xmlns="http://symfony.com/schema/dic/services"
183+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
184+
xsi:schemaLocation="http://symfony.com/schema/dic/services
185+
https://symfony.com/schema/dic/services/services-1.0.xsd">
186+
187+
<services>
188+
<service id="App\ErrorHandler\ErrorRenderer\JsonLdErrorRenderer">
189+
<argument>true</argument>
190+
<tag name="error_handler.renderer"/>
191+
</service>
192+
</services>
193+
</container>
194+
195+
.. code-block:: php
196+
197+
// config/services.php
198+
use App\ErrorHandler\ErrorRenderer\JsonLdErrorRenderer;
199+
200+
$container->register(JsonLdErrorRenderer::class)
201+
->setArguments([true]);
202+
->addTag('error_handler.renderer');
203+
204+
.. _`RFC 7807`: https://tools.ietf.org/html/rfc7807
205+
.. _`JSON-LD format`: https://en.wikipedia.org/wiki/JSON-LD

‎configuration/front_controllers_and_kernel.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,8 @@ new kernel.
123123
.. index::
124124
single: Configuration; Debug mode
125125

126+
.. _debug-mode:
127+
126128
Debug Mode
127129
~~~~~~~~~~
128130

‎create_framework/http_kernel_httpkernel_class.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ Our code is now much more concise and surprisingly more robust and more
6969
powerful than ever. For instance, use the built-in ``ExceptionListener`` to
7070
make your error management configurable::
7171

72-
$errorHandler = function (Symfony\Component\Debug\Exception\FlattenException $exception) {
72+
$errorHandler = function (Symfony\Component\ErrorCatcher\Exception\FlattenException $exception) {
7373
$msg = 'Something went wrong! ('.$exception->getMessage().')';
7474

7575
return new Response($msg, $exception->getStatusCode());
@@ -91,7 +91,7 @@ The error controller reads as follows::
9191
// example.com/src/Calendar/Controller/ErrorController.php
9292
namespace Calendar\Controller;
9393

94-
use Symfony\Component\Debug\Exception\FlattenException;
94+
use Symfony\Component\ErrorCatcher\Exception\FlattenException;
9595
use Symfony\Component\HttpFoundation\Response;
9696

9797
class ErrorController

0 commit comments

Comments
 (0)