From 67b244636d71bc398997ab85eb81412a8dea74b5 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 2 Jul 2019 15:06:46 +0200 Subject: [PATCH 1/4] Documented the ErrorCatcher component --- components/debug.rst | 46 +--- components/error_catcher.rst | 205 ++++++++++++++++++ .../front_controllers_and_kernel.rst | 2 + .../http_kernel_httpkernel_class.rst | 4 +- 4 files changed, 214 insertions(+), 43 deletions(-) create mode 100644 components/error_catcher.rst diff --git a/components/debug.rst b/components/debug.rst index 015376d9095..b8da5f31d4e 100644 --- a/components/debug.rst +++ b/components/debug.rst @@ -12,7 +12,7 @@ Installation .. code-block:: terminal - $ composer require symfony/debug + $ composer require --dev symfony/debug .. include:: /components/require_autoload.rst.inc @@ -26,50 +26,16 @@ Enable all of them by calling this method:: Debug::enable(); -The :method:`Symfony\\Component\\Debug\\Debug::enable` method registers an -error handler, an exception handler and -:ref:`a special class loader `. - -Read the following sections for more information about the different available -tools. - .. caution:: You should never enable the debug tools, except for the error handler, in a production environment as they might disclose sensitive information to the user. -Enabling the Error Handler --------------------------- - -The :class:`Symfony\\Component\\Debug\\ErrorHandler` class catches PHP errors -and converts them to exceptions (of class :phpclass:`ErrorException` or -:class:`Symfony\\Component\\Debug\\Exception\\FatalErrorException` for PHP -fatal errors):: - - use Symfony\Component\Debug\ErrorHandler; - - ErrorHandler::register(); - -This error handler is enabled by default in the production environment when the -application uses the FrameworkBundle because it generates better error logs. +.. deprecated:: 4.4 -Enabling the Exception Handler ------------------------------- - -The :class:`Symfony\\Component\\Debug\\ExceptionHandler` class catches -uncaught PHP exceptions and converts them to a nice PHP response. It is useful -in debug mode to replace the default PHP/XDebug output with something prettier -and more useful:: - - use Symfony\Component\Debug\ExceptionHandler; - - ExceptionHandler::register(); - -.. note:: - - If the :doc:`HttpFoundation component ` is - available, the handler uses a Symfony Response object; if not, it falls - back to a regular PHP response. + In Symfony versions before 4.4, this component also provided error and + exception handlers. In Symfony 4.4 they were deprecated in favor of their + equivalent handlers included in the new :doc:`ErrorCatcher component `. .. _component-debug-class-loader: @@ -87,5 +53,3 @@ Using the ``DebugClassLoader`` is done by calling its static use Symfony\Component\Debug\DebugClassLoader; DebugClassLoader::enable(); - -.. _Packagist: https://packagist.org/packages/symfony/debug diff --git a/components/error_catcher.rst b/components/error_catcher.rst new file mode 100644 index 00000000000..a6aa7abd30e --- /dev/null +++ b/components/error_catcher.rst @@ -0,0 +1,205 @@ +.. index:: + single: Error + single: Exception + single: Components; ErrorCatcher + +The ErrorCatcher Component +========================== + + The ErrorCatcher component converts PHP errors and exceptions into other + formats such as JSON and HTML and renders them. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/error-catcher + +.. include:: /components/require_autoload.rst.inc + +Usage +----- + +The ErrorCatcher component provides several handlers and renderers to convert +PHP errors and exceptions into other formats easier to debug when working with +HTTP applications. + +.. TODO: how are these handlers enabled in the app? (Previously: Debug::enable()) + +Handling PHP Errors and Exceptions +---------------------------------- + +Enabling the Error Handler +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :class:`Symfony\\Component\\ErrorCatcher\\ErrorHandler` class catches PHP +errors and converts them to exceptions (of class :phpclass:`ErrorException` or +:class:`Symfony\\Component\\ErrorCatcher\\Exception\\FatalErrorException` for +PHP fatal errors):: + + use Symfony\Component\ErrorCatcher\ErrorHandler; + + ErrorHandler::register(); + +This error handler is enabled by default in the production environment when the +application uses the FrameworkBundle because it generates better error logs. + +Enabling the Exception Handler +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :class:`Symfony\\Component\\ErrorCatcher\\ExceptionHandler` class catches +uncaught PHP exceptions and converts them to a nice PHP response. It is useful +in :ref:`debug mode ` to replace the default PHP/XDebug output with +something prettier and more useful:: + + use Symfony\Component\ErrorCatcher\ExceptionHandler; + + ExceptionHandler::register(); + +.. note:: + + If the :doc:`HttpFoundation component ` is + available, the handler uses a Symfony Response object; if not, it falls + back to a regular PHP response. + +Rendering PHP Errors and Exceptions +----------------------------------- + +Another feature provided by this component are the "error renderers", which +converts PHP errors and exceptions into other formats such as JSON and HTML:: + + use Symfony\Component\ErrorHandler\ErrorRenderer\ErrorRenderer; + use Symfony\Component\ErrorHandler\ErrorRenderer\HtmlErrorRenderer; + use Symfony\Component\ErrorHandler\ErrorRenderer\JsonErrorRenderer; + + $renderers = [ + new HtmlErrorRenderer(), + new JsonErrorRenderer(), + // ... + ]; + $errorRenderer = new ErrorRenderer($renderers); + + /** @var Symfony\Component\ErrorHandler\Exception\FlattenException */ + $exception = ...; + /** @var Symfony\Component\HttpFoundation\Request */ + $request = ...; + + return new Response( + $errorRenderer->render($exception, $request->getRequestFormat()), + $exception->getStatusCode(), + $exception->getHeaders() + ); + +Built-in Error Renderers +~~~~~~~~~~~~~~~~~~~~~~~~ + +This component provides error renderers for the most common needs: + + * :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\HtmlErrorRenderer` + renders errors in HTML format; + * :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\JsonErrorRenderer` + renders errors in JsonErrorRenderer format and it's compliant with the + `RFC 7807`_ standard; + * :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\XmlErrorRenderer` + renders errors in XML and Atom formats. It's compliant with the `RFC 7807`_ + standard; + * :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\TxtErrorRenderer` + renders errors in regular text format. + +Adding a Custom Error Renderer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Error renderers are PHP classes that implement the +:class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\ErrorRendererInterface`. +For example, if you need to render errors in `JSON-LD format`_, create this +class anywhere in your project:: + + namespace App\ErrorHandler\ErrorRenderer; + + use Symfony\Component\ErrorHandler\ErrorRenderer\ErrorRendererInterface; + use Symfony\Component\ErrorHandler\Exception\FlattenException; + + class JsonLdErrorRenderer implements ErrorRendererInterface + { + private $debug; + + public static function getFormat(): string + { + return 'jsonld'; + } + + public function __construct(bool $debug = true) + { + $this->debug = $debug; + } + + 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, +:ref:`register it as a service ` and +:doc:`tag it ` with the ``error_handler.renderer`` +tag. + +.. configuration-block:: + + .. code-block:: yaml + + # config/services.yaml + services: + App\ErrorHandler\ErrorRenderer\JsonLdErrorRenderer: + arguments: ['%kernel.debug%'] + tags: ['error_handler.renderer'] + + .. code-block:: xml + + + + + + + + true + + + + + + .. code-block:: php + + // config/services.php + use App\ErrorHandler\ErrorRenderer\JsonLdErrorRenderer; + + $container->register(JsonLdErrorRenderer::class) + ->setArguments([true]); + ->addTag('error_handler.renderer'); + +.. _`RFC 7807`: https://tools.ietf.org/html/rfc7807 +.. _`JSON-LD format`: https://en.wikipedia.org/wiki/JSON-LD diff --git a/configuration/front_controllers_and_kernel.rst b/configuration/front_controllers_and_kernel.rst index d986d7471b7..bdeac5ed93d 100644 --- a/configuration/front_controllers_and_kernel.rst +++ b/configuration/front_controllers_and_kernel.rst @@ -123,6 +123,8 @@ new kernel. .. index:: single: Configuration; Debug mode +.. _debug-mode: + Debug Mode ~~~~~~~~~~ diff --git a/create_framework/http_kernel_httpkernel_class.rst b/create_framework/http_kernel_httpkernel_class.rst index 43dd45b7182..e27f7e99d14 100644 --- a/create_framework/http_kernel_httpkernel_class.rst +++ b/create_framework/http_kernel_httpkernel_class.rst @@ -69,7 +69,7 @@ Our code is now much more concise and surprisingly more robust and more powerful than ever. For instance, use the built-in ``ExceptionListener`` to make your error management configurable:: - $errorHandler = function (Symfony\Component\Debug\Exception\FlattenException $exception) { + $errorHandler = function (Symfony\Component\ErrorCatcher\Exception\FlattenException $exception) { $msg = 'Something went wrong! ('.$exception->getMessage().')'; return new Response($msg, $exception->getStatusCode()); @@ -91,7 +91,7 @@ The error controller reads as follows:: // example.com/src/Calendar/Controller/ErrorController.php namespace Calendar\Controller; - use Symfony\Component\Debug\Exception\FlattenException; + use Symfony\Component\ErrorCatcher\Exception\FlattenException; use Symfony\Component\HttpFoundation\Response; class ErrorController From 74472737cba1f3aab767e4931bb310e06f672892 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 Jul 2019 10:35:19 +0200 Subject: [PATCH 2/4] Fixes --- components/error_catcher.rst | 47 ++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/components/error_catcher.rst b/components/error_catcher.rst index a6aa7abd30e..85f0681fa3d 100644 --- a/components/error_catcher.rst +++ b/components/error_catcher.rst @@ -69,24 +69,24 @@ Rendering PHP Errors and Exceptions Another feature provided by this component are the "error renderers", which converts PHP errors and exceptions into other formats such as JSON and HTML:: - use Symfony\Component\ErrorHandler\ErrorRenderer\ErrorRenderer; - use Symfony\Component\ErrorHandler\ErrorRenderer\HtmlErrorRenderer; - use Symfony\Component\ErrorHandler\ErrorRenderer\JsonErrorRenderer; + use Symfony\Component\ErrorCatcher\ErrorRenderer\ErrorRenderer; + use Symfony\Component\ErrorCatcher\ErrorRenderer\HtmlErrorRenderer; + use Symfony\Component\ErrorCatcher\ErrorRenderer\JsonErrorRenderer; $renderers = [ new HtmlErrorRenderer(), new JsonErrorRenderer(), // ... ]; - $errorRenderer = new ErrorRenderer($renderers); + $errorFormatter = new ErrorFormatter($renderers); - /** @var Symfony\Component\ErrorHandler\Exception\FlattenException */ + /** @var Symfony\Component\ErrorCatcher\Exception\FlattenException */ $exception = ...; /** @var Symfony\Component\HttpFoundation\Request */ $request = ...; return new Response( - $errorRenderer->render($exception, $request->getRequestFormat()), + $errorFormatter->render($exception, $request->getRequestFormat()), $exception->getStatusCode(), $exception->getHeaders() ); @@ -96,29 +96,28 @@ Built-in Error Renderers This component provides error renderers for the most common needs: - * :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\HtmlErrorRenderer` + * :class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\HtmlErrorRenderer` renders errors in HTML format; - * :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\JsonErrorRenderer` - renders errors in JsonErrorRenderer format and it's compliant with the - `RFC 7807`_ standard; - * :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\XmlErrorRenderer` + * :class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\JsonErrorRenderer` + renders errors in JSON format and it's compliant with the `RFC 7807`_ standard; + * :class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\XmlErrorRenderer` renders errors in XML and Atom formats. It's compliant with the `RFC 7807`_ standard; - * :class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\TxtErrorRenderer` - renders errors in regular text format. + * :class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\TxtErrorRenderer` + renders errors in plain text format. Adding a Custom Error Renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Error renderers are PHP classes that implement the -:class:`Symfony\\Component\\ErrorHandler\\ErrorRenderer\\ErrorRendererInterface`. +:class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\ErrorRendererInterface`. For example, if you need to render errors in `JSON-LD format`_, create this class anywhere in your project:: - namespace App\ErrorHandler\ErrorRenderer; + namespace App\ErrorCatcher; - use Symfony\Component\ErrorHandler\ErrorRenderer\ErrorRendererInterface; - use Symfony\Component\ErrorHandler\Exception\FlattenException; + use Symfony\Component\ErrorCatcher\ErrorRenderer\ErrorRendererInterface; + use Symfony\Component\ErrorCatcher\Exception\FlattenException; class JsonLdErrorRenderer implements ErrorRendererInterface { @@ -162,7 +161,7 @@ class anywhere in your project:: To enable the new error renderer in the application, :ref:`register it as a service ` and -:doc:`tag it ` with the ``error_handler.renderer`` +:doc:`tag it ` with the ``error_catcher.renderer`` tag. .. configuration-block:: @@ -171,9 +170,9 @@ tag. # config/services.yaml services: - App\ErrorHandler\ErrorRenderer\JsonLdErrorRenderer: + App\ErrorCatcher\JsonLdErrorRenderer: arguments: ['%kernel.debug%'] - tags: ['error_handler.renderer'] + tags: ['error_catcher.renderer'] .. code-block:: xml @@ -185,9 +184,9 @@ tag. https://symfony.com/schema/dic/services/services-1.0.xsd"> - + true - + @@ -195,11 +194,11 @@ tag. .. code-block:: php // config/services.php - use App\ErrorHandler\ErrorRenderer\JsonLdErrorRenderer; + use App\ErrorCatcher\JsonLdErrorRenderer; $container->register(JsonLdErrorRenderer::class) ->setArguments([true]); - ->addTag('error_handler.renderer'); + ->addTag('error_catcher.renderer'); .. _`RFC 7807`: https://tools.ietf.org/html/rfc7807 .. _`JSON-LD format`: https://en.wikipedia.org/wiki/JSON-LD From e6facb429e2c6203aaf1642768be7736d5a37be4 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 12 Jul 2019 10:35:47 +0200 Subject: [PATCH 3/4] Renamed ErrorCatcher as ErrorRenderer --- .../{error_catcher.rst => error_renderer.rst} | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) rename components/{error_catcher.rst => error_renderer.rst} (75%) diff --git a/components/error_catcher.rst b/components/error_renderer.rst similarity index 75% rename from components/error_catcher.rst rename to components/error_renderer.rst index 85f0681fa3d..5c14fdac0f5 100644 --- a/components/error_catcher.rst +++ b/components/error_renderer.rst @@ -1,12 +1,12 @@ .. index:: single: Error single: Exception - single: Components; ErrorCatcher + single: Components; ErrorRenderer -The ErrorCatcher Component -========================== +The ErrorRenderer Component +=========================== - The ErrorCatcher component converts PHP errors and exceptions into other + The ErrorRenderer component converts PHP errors and exceptions into other formats such as JSON and HTML and renders them. Installation @@ -14,14 +14,14 @@ Installation .. code-block:: terminal - $ composer require symfony/error-catcher + $ composer require symfony/error-renderer .. include:: /components/require_autoload.rst.inc Usage ----- -The ErrorCatcher component provides several handlers and renderers to convert +The ErrorRenderer component provides several handlers and renderers to convert PHP errors and exceptions into other formats easier to debug when working with HTTP applications. @@ -33,12 +33,12 @@ Handling PHP Errors and Exceptions Enabling the Error Handler ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :class:`Symfony\\Component\\ErrorCatcher\\ErrorHandler` class catches PHP +The :class:`Symfony\\Component\\ErrorRenderer\\ErrorHandler` class catches PHP errors and converts them to exceptions (of class :phpclass:`ErrorException` or -:class:`Symfony\\Component\\ErrorCatcher\\Exception\\FatalErrorException` for +:class:`Symfony\\Component\\ErrorRenderer\\Exception\\FatalErrorException` for PHP fatal errors):: - use Symfony\Component\ErrorCatcher\ErrorHandler; + use Symfony\Component\ErrorRenderer\ErrorHandler; ErrorHandler::register(); @@ -48,12 +48,12 @@ application uses the FrameworkBundle because it generates better error logs. Enabling the Exception Handler ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :class:`Symfony\\Component\\ErrorCatcher\\ExceptionHandler` class catches +The :class:`Symfony\\Component\\ErrorRenderer\\ExceptionHandler` class catches uncaught PHP exceptions and converts them to a nice PHP response. It is useful in :ref:`debug mode ` to replace the default PHP/XDebug output with something prettier and more useful:: - use Symfony\Component\ErrorCatcher\ExceptionHandler; + use Symfony\Component\ErrorRenderer\ExceptionHandler; ExceptionHandler::register(); @@ -69,9 +69,9 @@ Rendering PHP Errors and Exceptions Another feature provided by this component are the "error renderers", which converts PHP errors and exceptions into other formats such as JSON and HTML:: - use Symfony\Component\ErrorCatcher\ErrorRenderer\ErrorRenderer; - use Symfony\Component\ErrorCatcher\ErrorRenderer\HtmlErrorRenderer; - use Symfony\Component\ErrorCatcher\ErrorRenderer\JsonErrorRenderer; + use Symfony\Component\ErrorRenderer\ErrorRenderer\ErrorRenderer; + use Symfony\Component\ErrorRenderer\ErrorRenderer\HtmlErrorRenderer; + use Symfony\Component\ErrorRenderer\ErrorRenderer\JsonErrorRenderer; $renderers = [ new HtmlErrorRenderer(), @@ -80,7 +80,7 @@ converts PHP errors and exceptions into other formats such as JSON and HTML:: ]; $errorFormatter = new ErrorFormatter($renderers); - /** @var Symfony\Component\ErrorCatcher\Exception\FlattenException */ + /** @var Symfony\Component\ErrorRenderer\Exception\FlattenException */ $exception = ...; /** @var Symfony\Component\HttpFoundation\Request */ $request = ...; @@ -96,28 +96,28 @@ Built-in Error Renderers This component provides error renderers for the most common needs: - * :class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\HtmlErrorRenderer` + * :class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\HtmlErrorRenderer` renders errors in HTML format; - * :class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\JsonErrorRenderer` + * :class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\JsonErrorRenderer` renders errors in JSON format and it's compliant with the `RFC 7807`_ standard; - * :class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\XmlErrorRenderer` + * :class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\XmlErrorRenderer` renders errors in XML and Atom formats. It's compliant with the `RFC 7807`_ standard; - * :class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\TxtErrorRenderer` + * :class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\TxtErrorRenderer` renders errors in plain text format. Adding a Custom Error Renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Error renderers are PHP classes that implement the -:class:`Symfony\\Component\\ErrorCatcher\\ErrorRenderer\\ErrorRendererInterface`. +:class:`Symfony\\Component\\ErrorRenderer\\ErrorRenderer\\ErrorRendererInterface`. For example, if you need to render errors in `JSON-LD format`_, create this class anywhere in your project:: - namespace App\ErrorCatcher; + namespace App\ErrorRenderer; - use Symfony\Component\ErrorCatcher\ErrorRenderer\ErrorRendererInterface; - use Symfony\Component\ErrorCatcher\Exception\FlattenException; + use Symfony\Component\ErrorRenderer\ErrorRenderer\ErrorRendererInterface; + use Symfony\Component\ErrorRenderer\Exception\FlattenException; class JsonLdErrorRenderer implements ErrorRendererInterface { @@ -170,7 +170,7 @@ tag. # config/services.yaml services: - App\ErrorCatcher\JsonLdErrorRenderer: + App\ErrorRenderer\JsonLdErrorRenderer: arguments: ['%kernel.debug%'] tags: ['error_catcher.renderer'] @@ -184,7 +184,7 @@ tag. https://symfony.com/schema/dic/services/services-1.0.xsd"> - + true @@ -194,7 +194,7 @@ tag. .. code-block:: php // config/services.php - use App\ErrorCatcher\JsonLdErrorRenderer; + use App\ErrorRenderer\JsonLdErrorRenderer; $container->register(JsonLdErrorRenderer::class) ->setArguments([true]); From 372224b10d31f2f2776155024edbde3c5611bd8c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 12 Jul 2019 10:36:36 +0200 Subject: [PATCH 4/4] Fixed a method name --- components/error_renderer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/error_renderer.rst b/components/error_renderer.rst index 5c14fdac0f5..89a7e99a4b5 100644 --- a/components/error_renderer.rst +++ b/components/error_renderer.rst @@ -155,7 +155,7 @@ class anywhere in your project:: .. tip:: - If the ``getformat()`` method of your error renderer matches one of formats + 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.