Skip to content

Commit 2c78789

Browse files
ycerutoyceruto
committed
Update with latest changes: ErrorRenderer and ErrorHandler components
1 parent b0723ef commit 2c78789

File tree

3 files changed

+109
-76
lines changed

3 files changed

+109
-76
lines changed

‎components/debug.rst

Lines changed: 1 addition & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -35,21 +35,4 @@ Enable all of them by calling this method::
3535

3636
In Symfony versions before 4.4, this component also provided error and
3737
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>`.
39-
40-
.. _component-debug-class-loader:
41-
42-
Debugging a Class Loader
43-
------------------------
44-
45-
The :class:`Symfony\\Component\\Debug\\DebugClassLoader` attempts to
46-
throw more helpful exceptions when a class isn't found by the registered
47-
autoloaders. All autoloaders that implement a ``findFile()`` method are replaced
48-
with a ``DebugClassLoader`` wrapper.
49-
50-
Using the ``DebugClassLoader`` is done by calling its static
51-
:method:`Symfony\\Component\\Debug\\DebugClassLoader::enable` method::
52-
53-
use Symfony\Component\Debug\DebugClassLoader;
54-
55-
DebugClassLoader::enable();
38+
equivalent handlers included in the new :doc:`ErrorHandler component </components/error_handler>`.

‎components/error_handler.rst

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
.. index::
2+
single: Debug
3+
single: Error
4+
single: Exception
5+
single: Components; ErrorHandler
6+
7+
The ErrorHandler Component
8+
==========================
9+
10+
The ErrorHandler component provides tools to manage errors and ease debugging PHP code.
11+
12+
Installation
13+
------------
14+
15+
.. code-block:: terminal
16+
17+
$ composer require symfony/error-handler
18+
19+
.. include:: /components/require_autoload.rst.inc
20+
21+
Usage
22+
-----
23+
24+
The ErrorHandler component provides several tools to help you debug PHP code.
25+
Enable all of them by calling this method::
26+
27+
use Symfony\Component\ErrorHandler\Debug;
28+
29+
Debug::enable();
30+
31+
The :method:`Symfony\\Component\\ErrorHandler\\Debug::enable` method registers an
32+
error handler, an exception handler and
33+
:ref:`a special class loader <component-debug-class-loader>`.
34+
35+
Read the following sections for more information about the different available
36+
tools.
37+
38+
.. caution::
39+
40+
You should never enable the debug tools, except for the error handler, in a
41+
production environment as they might disclose sensitive information to the user.
42+
43+
Handling PHP Errors and Exceptions
44+
----------------------------------
45+
46+
Enabling the Error Handler
47+
~~~~~~~~~~~~~~~~~~~~~~~~~~
48+
49+
The :class:`Symfony\\Component\\ErrorHandler\\ErrorHandler` class catches PHP
50+
errors and converts them to exceptions (of class :phpclass:`ErrorException` or
51+
:class:`Symfony\\Component\\ErrorHandler\\Exception\\FatalErrorException` for
52+
PHP fatal errors)::
53+
54+
use Symfony\Component\ErrorHandler\ErrorHandler;
55+
56+
ErrorHandler::register();
57+
58+
This error handler is enabled by default in the production environment when the
59+
application uses the FrameworkBundle because it generates better error logs.
60+
61+
Enabling the Exception Handler
62+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63+
64+
The :class:`Symfony\\Component\\ErrorHandler\\ExceptionHandler` class catches
65+
uncaught PHP exceptions and converts them to a nice PHP response. It is useful
66+
in :ref:`debug mode <debug-mode>` to replace the default PHP/XDebug output with
67+
something prettier and more useful::
68+
69+
use Symfony\Component\ErrorHandler\ExceptionHandler;
70+
71+
ExceptionHandler::register();
72+
73+
.. note::
74+
75+
If the :doc:`HttpFoundation component </components/http_foundation>` is
76+
available, the handler uses a Symfony Response object; if not, it falls
77+
back to a regular PHP response.
78+
79+
.. _component-debug-class-loader:
80+
81+
Debugging a Class Loader
82+
------------------------
83+
84+
The :class:`Symfony\\Component\\ErrorHandler\\DebugClassLoader` attempts to
85+
throw more helpful exceptions when a class isn't found by the registered
86+
autoloaders. All autoloaders that implement a ``findFile()`` method are replaced
87+
with a ``DebugClassLoader`` wrapper.
88+
89+
Using the ``DebugClassLoader`` is done by calling its static
90+
:method:`Symfony\\Component\\ErrorHandler\\DebugClassLoader::enable` method::
91+
92+
use Symfony\Component\ErrorHandler\DebugClassLoader;
93+
94+
DebugClassLoader::enable();

‎components/error_renderer.rst

Lines changed: 14 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -21,55 +21,11 @@ Installation
2121
Usage
2222
-----
2323

24-
The ErrorRenderer 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.
24+
The ErrorRenderer component provides several renderers to convert PHP errors and
25+
exceptions into other formats such as JSON and HTML easier to debug when working
26+
with HTTP applications::
2727

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\\ErrorRenderer\\ErrorHandler` class catches PHP
37-
errors and converts them to exceptions (of class :phpclass:`ErrorException` or
38-
:class:`Symfony\\Component\\ErrorRenderer\\Exception\\FatalErrorException` for
39-
PHP fatal errors)::
40-
41-
use Symfony\Component\ErrorRenderer\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\\ErrorRenderer\\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\ErrorRenderer\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\ErrorRenderer\ErrorRenderer\ErrorRenderer;
28+
use Symfony\Component\ErrorRenderer\ErrorRenderer;
7329
use Symfony\Component\ErrorRenderer\ErrorRenderer\HtmlErrorRenderer;
7430
use Symfony\Component\ErrorRenderer\ErrorRenderer\JsonErrorRenderer;
7531

@@ -78,15 +34,15 @@ converts PHP errors and exceptions into other formats such as JSON and HTML::
7834
new JsonErrorRenderer(),
7935
// ...
8036
];
81-
$errorFormatter = new ErrorFormatter($renderers);
37+
$errorRenderer = new ErrorRenderer($renderers);
8238

8339
/** @var Symfony\Component\ErrorRenderer\Exception\FlattenException */
8440
$exception = ...;
8541
/** @var Symfony\Component\HttpFoundation\Request */
8642
$request = ...;
8743

8844
return new Response(
89-
$errorFormatter->render($exception, $request->getRequestFormat()),
45+
$errorRenderer->render($exception, $request->getPreferredFormat()),
9046
$exception->getStatusCode(),
9147
$exception->getHeaders()
9248
);
@@ -123,14 +79,14 @@ class anywhere in your project::
12379
{
12480
private $debug;
12581

126-
public static function getFormat(): string
82+
public function __construct(bool $debug = true)
12783
{
128-
return 'jsonld';
84+
$this->debug = $debug;
12985
}
13086

131-
public function __construct(bool $debug = true)
87+
public static function getFormat(): string
13288
{
133-
$this->debug = $debug;
89+
return 'jsonld';
13490
}
13591

13692
public function render(FlattenException $exception): string
@@ -161,7 +117,7 @@ class anywhere in your project::
161117

162118
To enable the new error renderer in the application,
163119
:ref:`register it as a service <service-container-creating-service>` and
164-
:doc:`tag it </service_container/tags>` with the ``error_catcher.renderer``
120+
:doc:`tag it </service_container/tags>` with the ``error_renderer.renderer``
165121
tag.
166122

167123
.. configuration-block::
@@ -172,7 +128,7 @@ tag.
172128
services:
173129
App\ErrorRenderer\JsonLdErrorRenderer:
174130
arguments: ['%kernel.debug%']
175-
tags: ['error_catcher.renderer']
131+
tags: ['error_renderer.renderer']
176132
177133
.. code-block:: xml
178134
@@ -186,7 +142,7 @@ tag.
186142
<services>
187143
<service id="App\ErrorRenderer\JsonLdErrorRenderer">
188144
<argument>true</argument>
189-
<tag name="error_catcher.renderer"/>
145+
<tag name="error_renderer.renderer"/>
190146
</service>
191147
</services>
192148
</container>
@@ -198,7 +154,7 @@ tag.
198154
199155
$container->register(JsonLdErrorRenderer::class)
200156
->setArguments([true]);
201-
->addTag('error_catcher.renderer');
157+
->addTag('error_renderer.renderer');
202158
203159
.. _`RFC 7807`: https://tools.ietf.org/html/rfc7807
204160
.. _`JSON-LD format`: https://en.wikipedia.org/wiki/JSON-LD

0 commit comments

Comments
 (0)