Update with latest changes: ErrorRenderer and ErrorHandler components

Author: yceruto

components/debug.rst

@@ -35,7 +35,7 @@ Enable all of them by calling this method::
 
     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 </components/error_catcher>`.
+    equivalent handlers included in the new :doc:`ErrorHandler component </components/error_handler>`.
 
 .. _component-debug-class-loader:
 

components/error_handler.rst

@@ -0,0 +1,94 @@
+.. index::
+   single: Debug
+   single: Error
+   single: Exception
+   single: Components; ErrorHandler
+
+The ErrorHandler Component
+===================
+
+    The ErrorHandler component provides tools to manage errors and ease debugging PHP code.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/error-handler
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+The ErrorHandler component provides several tools to help you debug PHP code.
+Enable all of them by calling this method::
+
+    use Symfony\Component\ErrorHandler\Debug;
+
+    Debug::enable();
+
+The :method:`Symfony\\Component\\ErrorHandler\\Debug::enable` method registers an
+error handler, an exception handler and
+:ref:`a special class loader <component-debug-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.
+
+Handling PHP Errors and Exceptions
+----------------------------------
+
+Enabling the Error Handler
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :class:`Symfony\\Component\\ErrorHandler\\ErrorHandler` class catches PHP
+errors and converts them to exceptions (of class :phpclass:`ErrorException` or
+:class:`Symfony\\Component\\ErrorHandler\\Exception\\FatalErrorException` for
+PHP fatal errors)::
+
+    use Symfony\Component\ErrorHandler\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\\ErrorHandler\\ExceptionHandler` class catches
+uncaught PHP exceptions and converts them to a nice PHP response. It is useful
+in :ref:`debug mode <debug-mode>` to replace the default PHP/XDebug output with
+something prettier and more useful::
+
+    use Symfony\Component\ErrorHandler\ExceptionHandler;
+
+    ExceptionHandler::register();
+
+.. note::
+
+    If the :doc:`HttpFoundation component </components/http_foundation>` is
+    available, the handler uses a Symfony Response object; if not, it falls
+    back to a regular PHP response.
+
+.. _component-debug-class-loader:
+
+Debugging a Class Loader
+------------------------
+
+The :class:`Symfony\\Component\\ErrorHandler\\DebugClassLoader` attempts to
+throw more helpful exceptions when a class isn't found by the registered
+autoloaders. All autoloaders that implement a ``findFile()`` method are replaced
+with a ``DebugClassLoader`` wrapper.
+
+Using the ``DebugClassLoader`` is done by calling its static
+:method:`Symfony\\Component\\ErrorHandler\\DebugClassLoader::enable` method::
+
+    use Symfony\Component\ErrorHandler\DebugClassLoader;
+
+    DebugClassLoader::enable();

components/error_renderer.rst

@@ -21,55 +21,11 @@ Installation
 Usage
 -----
 
-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.
+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::
 
-.. 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\\ErrorRenderer\\ErrorHandler` class catches PHP
-errors and converts them to exceptions (of class :phpclass:`ErrorException` or
-:class:`Symfony\\Component\\ErrorRenderer\\Exception\\FatalErrorException` for
-PHP fatal errors)::
-
-    use Symfony\Component\ErrorRenderer\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\\ErrorRenderer\\ExceptionHandler` class catches
-uncaught PHP exceptions and converts them to a nice PHP response. It is useful
-in :ref:`debug mode <debug-mode>` to replace the default PHP/XDebug output with
-something prettier and more useful::
-
-    use Symfony\Component\ErrorRenderer\ExceptionHandler;
-
-    ExceptionHandler::register();
-
-.. note::
-
-    If the :doc:`HttpFoundation component </components/http_foundation>` 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\ErrorRenderer\ErrorRenderer\ErrorRenderer;
+    use Symfony\Component\ErrorRenderer\ErrorRenderer;
     use Symfony\Component\ErrorRenderer\ErrorRenderer\HtmlErrorRenderer;
     use Symfony\Component\ErrorRenderer\ErrorRenderer\JsonErrorRenderer;
 
@@ -78,15 +34,15 @@ converts PHP errors and exceptions into other formats such as JSON and HTML::
         new JsonErrorRenderer(),
         // ...
     ];
-    $errorFormatter = new ErrorFormatter($renderers);
+    $errorRenderer = new ErrorRenderer($renderers);
 
     /** @var Symfony\Component\ErrorRenderer\Exception\FlattenException */
     $exception = ...;
     /** @var Symfony\Component\HttpFoundation\Request */
     $request = ...;
 
     return new Response(
-        $errorFormatter->render($exception, $request->getRequestFormat()),
+        $errorRenderer->render($exception, $request->getPreferredFormat()),
         $exception->getStatusCode(),
         $exception->getHeaders()
     );
@@ -123,14 +79,14 @@ class anywhere in your project::
     {
         private $debug;
 
-        public static function getFormat(): string
+        public function __construct(bool $debug = true)
         {
-            return 'jsonld';
+            $this->debug = $debug;
         }
 
-        public function __construct(bool $debug = true)
+        public static function getFormat(): string
         {
-            $this->debug = $debug;
+            return 'jsonld';
         }
 
         public function render(FlattenException $exception): string
@@ -161,7 +117,7 @@ class anywhere in your project::
 
 To enable the new error renderer in the application,
 :ref:`register it as a service <service-container-creating-service>` and
-:doc:`tag it </service_container/tags>` with the ``error_catcher.renderer``
+:doc:`tag it </service_container/tags>` with the ``error_renderer.renderer``
 tag.
 
 .. configuration-block::
@@ -172,7 +128,7 @@ tag.
         services:
             App\ErrorRenderer\JsonLdErrorRenderer:
                 arguments: ['%kernel.debug%']
-                tags: ['error_catcher.renderer']
+                tags: ['error_renderer.renderer']
 
     .. code-block:: xml
 
@@ -186,7 +142,7 @@ tag.
             <services>
                 <service id="App\ErrorRenderer\JsonLdErrorRenderer">
                     <argument>true</argument>
-                    <tag name="error_catcher.renderer"/>
+                    <tag name="error_renderer.renderer"/>
                 </service>
             </services>
         </container>
@@ -198,7 +154,7 @@ tag.
 
         $container->register(JsonLdErrorRenderer::class)
             ->setArguments([true]);
-            ->addTag('error_catcher.renderer');
+            ->addTag('error_renderer.renderer');
 
 .. _`RFC 7807`: https://tools.ietf.org/html/rfc7807
 .. _`JSON-LD format`: https://en.wikipedia.org/wiki/JSON-LD