docs: add user guide

user_guide_src/source/general/errors.rst

@@ -168,3 +168,40 @@ This feature also works with user deprecations:
 
 For testing your application you may want to always throw on deprecations. You may configure this by
 setting the environment variable ``CODEIGNITER_SCREAM_DEPRECATIONS`` to a truthy value.
+
+.. _custom-exception-handlers:
+
+Custom Exception Handlers
+=========================
+
+.. versionadded:: 4.4.0
+
+If you need more control over how exceptions are displayed you can now define your own handlers and
+specify when they apply.
+
+Defining the New Handler
+------------------------
+
+The first step is to create a new class which implements ``CodeIgniter\Debug\ExceptionHandlerInterface``.
+You can also extend ``CodeIgniter\Debug\BaseExceptionHandler``.
+This class includes a number of utility methods that are used by the default exception handler.
+The new handler must implement a single method: ``handle()``:
+
+.. literalinclude:: errors/015.php
+
+This example defines the minimum amount of code typically needed - display a view and exit with the proper
+exit code. However, the ``BaseExceptionHandler`` provides a number of other helper functions and objects.
+
+Configuring the New Handler
+---------------------------
+
+Telling CodeIgniter to use your new exception handler class is done in the **app/Config/Exceptions.php**
+configuration file's ``handler()`` method:
+
+.. literalinclude:: errors/016.php
+
+You can use any logic your application needs to determine whether it should handle the exception, but the
+two most common are checking on the HTTP status code or the type of exception. If your class should handle
+it then return a new instance of that class:
+
+.. literalinclude:: errors/017.php

user_guide_src/source/general/errors/015.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Libraries;
+
+use CodeIgniter\Debug\BaseExceptionHandler;
+use CodeIgniter\Debug\ExceptionHandlerInterface;
+use CodeIgniter\HTTP\RequestInterface;
+use CodeIgniter\HTTP\ResponseInterface;
+use Throwable;
+
+class MyExceptionHandler extends BaseExceptionHandler implements ExceptionHandlerInterface
+{
+    // You can override the view path.
+    protected ?string $viewPath = APPPATH . 'Views/exception/';
+
+    public function handle(
+        Throwable $exception,
+        RequestInterface $request,
+        ResponseInterface $response,
+        int $statusCode,
+        int $exitCode
+    ): void {
+        $this->render($exception, $statusCode, $this->viewPath . "error_{$statusCode}.php");
+
+        exit($exitCode);
+    }
+}

user_guide_src/source/general/errors/016.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use CodeIgniter\Debug\ExceptionHandler;
+use CodeIgniter\Debug\ExceptionHandlerInterface;
+use Throwable;
+
+class Exceptions extends BaseConfig
+{
+    // ...
+
+    public function handler(int $statusCode, Throwable $exception): ExceptionHandlerInterface
+    {
+        return new ExceptionHandler($this);
+    }
+}

user_guide_src/source/general/errors/017.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use CodeIgniter\Debug\ExceptionHandlerInterface;
+use CodeIgniter\Exceptions\PageNotFoundException;
+use Throwable;
+
+class Exceptions extends BaseConfig
+{
+    // ...
+
+    public function handler(int $statusCode, Throwable $exception): ExceptionHandlerInterface
+    {
+        if (in_array($statusCode, [400, 404, 500], true)) {
+            return new \App\Libraries\MyExceptionHandler($this);
+        }
+
+        if ($exception instanceof PageNotFoundException) {
+            return new \App\Libraries\MyExceptionHandler($this);
+        }
+
+        return new \CodeIgniter\Debug\ExceptionHandler($this);
+    }
+}