Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitd216423

Browse files
committed
minor#12187 Documenting ErrorRenderer and ErrorHandler components (javiereguiluz, yceruto)
This PR was merged into the 4.4 branch.Discussion----------Documenting ErrorRenderer and ErrorHandler componentsReplace#11864Closes#12193#12009#11980#12015#12019#12029Should we remove the whole Debug component documentation? or remove only the details and say it's deprecated?Commits-------8cc084f documenting the ErrorHandler::call method3ea9817 fix service definition5a025c9 fix example5136a17 Update with latest changes: ErrorRenderer and ErrorHandler componentsb0723ef Fixed a method nameb600b3c Renamed ErrorCatcher as ErrorRenderer4e333c1 Fixesb2a1a9b Documented the ErrorCatcher component
2 parentse5fa340 +8cc084f commitd216423

File tree

6 files changed

+320
-60
lines changed

6 files changed

+320
-60
lines changed

‎components/debug.rst‎

Lines changed: 5 additions & 56 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--devsymfony/debug
1616
1717
..include::/components/require_autoload.rst.inc
1818

@@ -26,64 +26,13 @@ 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::
69-
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.
73-
74-
.. _component-debug-class-loader:
75-
76-
Debugging a Class Loader
77-
------------------------
78-
79-
The:class:`Symfony\\Component\\Debug\\DebugClassLoader` attempts to
80-
throw more helpful exceptions when a class isn't found by the registered
81-
autoloaders. All autoloaders that implement a ``findFile()`` method are replaced
82-
with a ``DebugClassLoader`` wrapper.
83-
84-
Using the ``DebugClassLoader`` is done by calling its static
85-
:method:`Symfony\\Component\\Debug\\DebugClassLoader::enable` method::
86-
87-
use Symfony\Component\Debug\DebugClassLoader;
34+
..deprecated::4.4
8835

89-
DebugClassLoader::enable();
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:`ErrorHandler component</components/error_handler>`.

‎components/error_handler.rst‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
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+
Catches PHP errors and turn them into exceptions
80+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81+
82+
Most PHP core functions were written before exception handling was introduced to the
83+
language and most of this functions do not throw an exception on failure. Instead,
84+
they return ``false`` in case of error.
85+
86+
Let's take the following code example::
87+
88+
$data = json_decode(file_get_contents($filename), true);
89+
$data['read_at'] = date($datetimeFormat);
90+
file_put_contents($filename, json_encode($data));
91+
92+
All these functions ``file_get_contents``, ``json_decode``, ``date``, ``json_encode``
93+
and ``file_put_contents`` will return ``false`` or ``null`` on error, having to
94+
deal with those failures manually::
95+
96+
$content = @file_get_contents($filename);
97+
if (false === $content) {
98+
throw new \RuntimeException('Could not load file.');
99+
}
100+
$data = @json_decode($content, true);
101+
if (null === $data) {
102+
throw new \RuntimeException('File does not contain valid JSON.');
103+
}
104+
$datetime = @date($datetimeFormat);
105+
if (false === $datetime) {
106+
throw new \RuntimeException('Invalid datetime format.');
107+
}
108+
// ...
109+
110+
..note::
111+
112+
Since PHP 7.3 `json_decode`_ function will accept a new ``JSON_THROW_ON_ERROR`` option
113+
that will let ``json_decode`` throw an exception instead of returning ``null`` on error.
114+
However, it is not enabled by default, so you will need to explicitly configure it.
115+
116+
To simplify this behavior the:class:`Symfony\\Component\\ErrorHandler\\ErrorHandler` class
117+
provides a:method:`Symfony\\Component\\ErrorHandler\\ErrorHandler::call` method that will
118+
automatically throw an exception when such a failure occurs. This method will accept a ``callable``
119+
parameter and then the arguments needed to call it, returning back the result::
120+
121+
$content = ErrorHandler::call('file_get_contents', $filename);
122+
123+
This way, you could use a ``\Closure`` function to wrap a portion of code and be sure that it
124+
breaks even if the `@-silencing operator`_ is used::
125+
126+
$data = ErrorHandler::call(static function () use ($filename, $datetimeFormat) {
127+
$data = json_decode(file_get_contents($filename), true);
128+
$data['read_at'] = date($datetimeFormat);
129+
file_put_contents($filename, json_encode($data));
130+
131+
return $data;
132+
});
133+
134+
.. _component-debug-class-loader:
135+
136+
Debugging a Class Loader
137+
------------------------
138+
139+
The:class:`Symfony\\Component\\ErrorHandler\\DebugClassLoader` attempts to
140+
throw more helpful exceptions when a class isn't found by the registered
141+
autoloaders. All autoloaders that implement a ``findFile()`` method are replaced
142+
with a ``DebugClassLoader`` wrapper.
143+
144+
Using the ``DebugClassLoader`` is done by calling its static
145+
:method:`Symfony\\Component\\ErrorHandler\\DebugClassLoader::enable` method::
146+
147+
use Symfony\Component\ErrorHandler\DebugClassLoader;
148+
149+
DebugClassLoader::enable();
150+
151+
.. _`@-silencing operator`:https://php.net/manual/en/function.json-decode.php
152+
.. _`json_decode`:https://php.net/manual/en/language.operators.errorcontrol.php

‎components/error_renderer.rst‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
..index::
2+
single: Error
3+
single: Exception
4+
single: Components; ErrorRenderer
5+
6+
The ErrorRenderer Component
7+
===========================
8+
9+
The ErrorRenderer 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-renderer
18+
19+
..include::/components/require_autoload.rst.inc
20+
21+
Usage
22+
-----
23+
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::
27+
28+
use Symfony\Component\ErrorRenderer\ErrorRenderer;
29+
use Symfony\Component\ErrorRenderer\ErrorRenderer\HtmlErrorRenderer;
30+
use Symfony\Component\ErrorRenderer\ErrorRenderer\JsonErrorRenderer;
31+
use Symfony\Component\ErrorRenderer\Exception\FlattenException;
32+
use Symfony\Component\HttpFoundation\Response;
33+
34+
$renderers = [
35+
new HtmlErrorRenderer(),
36+
new JsonErrorRenderer(),
37+
// ...
38+
];
39+
$errorRenderer = new ErrorRenderer($renderers);
40+
41+
try {
42+
// ...
43+
} catch (\Throwable $e) {
44+
$e = FlattenException::createFromThrowable($e);
45+
46+
return new Response($errorRenderer->render($e, 'json'), 500, ['Content-Type' => 'application/json']);
47+
}
48+
49+
Built-in Error Renderers
50+
~~~~~~~~~~~~~~~~~~~~~~~~
51+
52+
This component provides error renderers for the most common needs:
53+
54+
*:class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\HtmlErrorRenderer`
55+
renders errors in HTML format;
56+
*:class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\JsonErrorRenderer`
57+
renders errors in JSON format and it's compliant with the `RFC 7807`_ standard;
58+
*:class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\XmlErrorRenderer`
59+
renders errors in XML and Atom formats. It's compliant with the `RFC 7807`_
60+
standard;
61+
*:class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\TxtErrorRenderer`
62+
renders errors in plain text format.
63+
64+
Adding a Custom Error Renderer
65+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66+
67+
Error renderers are PHP classes that implement the
68+
:class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\ErrorRendererInterface`.
69+
For example, if you need to render errors in `JSON-LD format`_, create this
70+
class anywhere in your project::
71+
72+
namespace App\ErrorRenderer;
73+
74+
use Symfony\Component\ErrorRenderer\ErrorRenderer\ErrorRendererInterface;
75+
use Symfony\Component\ErrorRenderer\Exception\FlattenException;
76+
77+
class JsonLdErrorRenderer implements ErrorRendererInterface
78+
{
79+
private $debug;
80+
81+
public function __construct(bool $debug = true)
82+
{
83+
$this->debug = $debug;
84+
}
85+
86+
public static function getFormat(): string
87+
{
88+
return 'jsonld';
89+
}
90+
91+
public function render(FlattenException $exception): string
92+
{
93+
$content = [
94+
'@id' => 'https://example.com',
95+
'@type' => 'error',
96+
'@context' => [
97+
'title' => $exception->getTitle(),
98+
'code' => $exception->getStatusCode(),
99+
'message' => $exception->getMessage(),
100+
],
101+
];
102+
103+
if ($this->debug) {
104+
$content['@context']['exceptions'] = $exception->toArray();
105+
}
106+
107+
return (string) json_encode($content);
108+
}
109+
}
110+
111+
..tip::
112+
113+
If the ``getFormat()`` method of your error renderer matches one of formats
114+
supported by the built-in renderers, the built-in renderer is replaced by
115+
your custom renderer.
116+
117+
To enable the new error renderer in the application,
118+
:ref:`register it as a service<service-container-creating-service>` and
119+
:doc:`tag it</service_container/tags>` with the ``error_renderer.renderer``
120+
tag.
121+
122+
..configuration-block::
123+
124+
..code-block::yaml
125+
126+
# config/services.yaml
127+
services:
128+
App\ErrorRenderer\JsonLdErrorRenderer:
129+
arguments:['%kernel.debug%']
130+
tags:['error_renderer.renderer']
131+
132+
..code-block::xml
133+
134+
<!-- config/services.xml-->
135+
<?xml version="1.0" encoding="UTF-8" ?>
136+
<containerxmlns="http://symfony.com/schema/dic/services"
137+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
138+
xsi:schemaLocation="http://symfony.com/schema/dic/services
139+
https://symfony.com/schema/dic/services/services-1.0.xsd">
140+
141+
<services>
142+
<serviceid="App\ErrorRenderer\JsonLdErrorRenderer">
143+
<argument>%kernel.debug%</argument>
144+
<tagname="error_renderer.renderer"/>
145+
</service>
146+
</services>
147+
</container>
148+
149+
..code-block::php
150+
151+
// config/services.php
152+
use App\ErrorRenderer\JsonLdErrorRenderer;
153+
154+
$container->register(JsonLdErrorRenderer::class)
155+
->setArguments([$container->getParameter('kernel.debug')]);
156+
->addTag('error_renderer.renderer');
157+
158+
.. _`RFC 7807`:https://tools.ietf.org/html/rfc7807
159+
.. _`JSON-LD format`:https://en.wikipedia.org/wiki/JSON-LD

‎components/http_kernel.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -554,7 +554,7 @@ below for more details).
554554
The listener has several goals:
555555

556556
1) The thrown exception is converted into a
557-
:class:`Symfony\\Component\\Debug\\Exception\\FlattenException`
557+
:class:`Symfony\\Component\\ErrorRenderer\\Exception\\FlattenException`
558558
object, which contains all the information about the request, but which
559559
can be printed and serialized.
560560

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp