feat: add Debug\ExceptionHandler

app/Config/Exceptions.php

@@ -3,7 +3,10 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use CodeIgniter\Debug\ExceptionHandler;
+use CodeIgniter\Debug\ExceptionHandlerInterface;
 use Psr\Log\LogLevel;
+use Throwable;
 
 /**
  * Setup how the exception handler works.
@@ -74,4 +77,28 @@ class Exceptions extends BaseConfig
      * to capture logging the deprecations.
      */
     public string $deprecationLogLevel = LogLevel::WARNING;
+
+    /*
+     * DEFINE THE HANDLERS USED
+     * --------------------------------------------------------------------------
+     * Given the HTTP status code, returns exception handler that
+     * should be used to deal with this error. By default, it will run CodeIgniter's
+     * default handler and display the error information in the expected format
+     * for CLI, HTTP, or AJAX requests, as determined by is_cli() and the expected
+     * response format.
+     *
+     * Custom handlers can be returned if you want to handle one or more specific
+     * error codes yourself like:
+     *
+     *      if (in_array($statusCode, [400, 404, 500])) {
+     *          return new \App\Libraries\MyExceptionHandler();
+     *      }
+     *      if ($exception instanceOf PageNotFoundException) {
+     *          return new \App\Libraries\MyExceptionHandler();
+     *      }
+     */
+    public function handler(int $statusCode, Throwable $exception): ExceptionHandlerInterface
+    {
+        return new ExceptionHandler($this);
+    }
 }

system/Debug/BaseExceptionHandler.php

@@ -0,0 +1,233 @@
+<?php
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Debug;
+
+use CodeIgniter\HTTP\RequestInterface;
+use CodeIgniter\HTTP\ResponseInterface;
+use Config\Exceptions as ExceptionsConfig;
+use Throwable;
+
+/**
+ * Provides common functions for exception handlers,
+ * especially around displaying the output.
+ */
+abstract class BaseExceptionHandler
+{
+    /**
+     * Config for debug exceptions.
+     */
+    protected ExceptionsConfig $config;
+
+    /**
+     * Nesting level of the output buffering mechanism
+     */
+    protected int $obLevel;
+
+    /**
+     * The path to the directory containing the
+     * cli and html error view directories.
+     */
+    protected ?string $viewPath = null;
+
+    public function __construct(ExceptionsConfig $config)
+    {
+        $this->config = $config;
+
+        $this->obLevel = ob_get_level();
+
+        if ($this->viewPath === null) {
+            $this->viewPath = rtrim($this->config->errorViewPath, '\\/ ') . DIRECTORY_SEPARATOR;
+        }
+    }
+
+    /**
+     * The main entry point into the handler.
+     *
+     * @return void
+     */
+    abstract public function handle(
+        Throwable $exception,
+        RequestInterface $request,
+        ResponseInterface $response,
+        int $statusCode,
+        int $exitCode
+    );
+
+    /**
+     * Gathers the variables that will be made available to the view.
+     */
+    protected function collectVars(Throwable $exception, int $statusCode): array
+    {
+        $trace = $exception->getTrace();
+
+        if ($this->config->sensitiveDataInTrace !== []) {
+            $this->maskSensitiveData($trace, $this->config->sensitiveDataInTrace);
+        }
+
+        return [
+            'title'   => get_class($exception),
+            'type'    => get_class($exception),
+            'code'    => $statusCode,
+            'message' => $exception->getMessage(),
+            'file'    => $exception->getFile(),
+            'line'    => $exception->getLine(),
+            'trace'   => $trace,
+        ];
+    }
+
+    /**
+     * Mask sensitive data in the trace.
+     *
+     * @param array|object $trace
+     */
+    protected function maskSensitiveData(&$trace, array $keysToMask, string $path = '')
+    {
+        foreach ($keysToMask as $keyToMask) {
+            $explode = explode('/', $keyToMask);
+            $index   = end($explode);
+
+            if (strpos(strrev($path . '/' . $index), strrev($keyToMask)) === 0) {
+                if (is_array($trace) && array_key_exists($index, $trace)) {
+                    $trace[$index] = '******************';
+                } elseif (is_object($trace) && property_exists($trace, $index) && isset($trace->{$index})) {
+                    $trace->{$index} = '******************';
+                }
+            }
+        }
+
+        if (is_object($trace)) {
+            $trace = get_object_vars($trace);
+        }
+
+        if (is_array($trace)) {
+            foreach ($trace as $pathKey => $subarray) {
+                $this->maskSensitiveData($subarray, $keysToMask, $path . '/' . $pathKey);
+            }
+        }
+    }
+
+    /**
+     * Describes memory usage in real-world units. Intended for use
+     * with memory_get_usage, etc.
+     *
+     * @used-by app/Views/errors/html/error_exception.php
+     */
+    protected static function describeMemory(int $bytes): string
+    {
+        helper('number');
+
+        return number_to_size($bytes, 2);
+    }
+
+    /**
+     * Creates a syntax-highlighted version of a PHP file.
+     *
+     * @used-by app/Views/errors/html/error_exception.php
+     *
+     * @return bool|string
+     */
+    protected static function highlightFile(string $file, int $lineNumber, int $lines = 15)
+    {
+        if (empty($file) || ! is_readable($file)) {
+            return false;
+        }
+
+        // Set our highlight colors:
+        if (function_exists('ini_set')) {
+            ini_set('highlight.comment', '#767a7e; font-style: italic');
+            ini_set('highlight.default', '#c7c7c7');
+            ini_set('highlight.html', '#06B');
+            ini_set('highlight.keyword', '#f1ce61;');
+            ini_set('highlight.string', '#869d6a');
+        }
+
+        try {
+            $source = file_get_contents($file);
+        } catch (Throwable $e) {
+            return false;
+        }
+
+        $source = str_replace(["\r\n", "\r"], "\n", $source);
+        $source = explode("\n", highlight_string($source, true));
+        $source = str_replace('<br />', "\n", $source[1]);
+        $source = explode("\n", str_replace("\r\n", "\n", $source));
+
+        // Get just the part to show
+        $start = max($lineNumber - (int) round($lines / 2), 0);
+
+        // Get just the lines we need to display, while keeping line numbers...
+        $source = array_splice($source, $start, $lines, true);
+
+        // Used to format the line number in the source
+        $format = '% ' . strlen((string) ($start + $lines)) . 'd';
+
+        $out = '';
+        // Because the highlighting may have an uneven number
+        // of open and close span tags on one line, we need
+        // to ensure we can close them all to get the lines
+        // showing correctly.
+        $spans = 1;
+
+        foreach ($source as $n => $row) {
+            $spans += substr_count($row, '<span') - substr_count($row, '</span');
+            $row = str_replace(["\r", "\n"], ['', ''], $row);
+
+            if (($n + $start + 1) === $lineNumber) {
+                preg_match_all('#<[^>]+>#', $row, $tags);
+
+                $out .= sprintf(
+                    "<span class='line highlight'><span class='number'>{$format}</span> %s\n</span>%s",
+                    $n + $start + 1,
+                    strip_tags($row),
+                    implode('', $tags[0])
+                );
+            } else {
+                $out .= sprintf('<span class="line"><span class="number">' . $format . '</span> %s', $n + $start + 1, $row) . "\n";
+            }
+        }
+
+        if ($spans > 0) {
+            $out .= str_repeat('</span>', $spans);
+        }
+
+        return '<pre><code>' . $out . '</code></pre>';
+    }
+
+    /**
+     * Given an exception and status code will display the error to the client.
+     *
+     * @param string|null $viewFile
+     */
+    protected function render(Throwable $exception, int $statusCode, $viewFile = null): void
+    {
+        if (empty($viewFile) || ! is_file($viewFile)) {
+            echo 'The error view files were not found. Cannot render exception trace.';
+
+            exit(1);
+        }
+
+        if (ob_get_level() > $this->obLevel + 1) {
+            ob_end_clean();
+        }
+
+        echo(function () use ($exception, $statusCode, $viewFile): string {
+            $vars = $this->collectVars($exception, $statusCode);
+            extract($vars, EXTR_SKIP);
+
+            // CLI error views output to STDERR/STDOUT, so ob_start() does not work.
+            ob_start();
+            include $viewFile;
+
+            return ob_get_clean();
+        })();
+    }
+}

system/Debug/ExceptionHandler.php

@@ -0,0 +1,149 @@
+<?php
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Debug;
+
+use CodeIgniter\API\ResponseTrait;
+use CodeIgniter\Exceptions\PageNotFoundException;
+use CodeIgniter\HTTP\Exceptions\HTTPException;
+use CodeIgniter\HTTP\IncomingRequest;
+use CodeIgniter\HTTP\RequestInterface;
+use CodeIgniter\HTTP\ResponseInterface;
+use Config\Paths;
+use Throwable;
+
+final class ExceptionHandler extends BaseExceptionHandler implements ExceptionHandlerInterface
+{
+    use ResponseTrait;
+
+    /**
+     * ResponseTrait needs this.
+     */
+    private ?RequestInterface $request = null;
+
+    /**
+     * ResponseTrait needs this.
+     */
+    private ?ResponseInterface $response = null;
+
+    /**
+     * Determines the correct way to display the error.
+     *
+     * @return void
+     */
+    public function handle(
+        Throwable $exception,
+        RequestInterface $request,
+        ResponseInterface $response,
+        int $statusCode,
+        int $exitCode
+    ) {
+        // ResponseTrait needs these properties.
+        $this->request  = $request;
+        $this->response = $response;
+
+        if ($request instanceof IncomingRequest) {
+            try {
+                $response->setStatusCode($statusCode);
+            } catch (HTTPException $e) {
+                // Workaround for invalid HTTP status code.
+                $statusCode = 500;
+                $response->setStatusCode($statusCode);
+            }
+
+            if (! headers_sent()) {
+                header(
+                    sprintf(
+                        'HTTP/%s %s %s',
+                        $request->getProtocolVersion(),
+                        $response->getStatusCode(),
+                        $response->getReasonPhrase()
+                    ),
+                    true,
+                    $statusCode
+                );
+            }
+
+            if (strpos($request->getHeaderLine('accept'), 'text/html') === false) {
+                $data = (ENVIRONMENT === 'development' || ENVIRONMENT === 'testing')
+                    ? $this->collectVars($exception, $statusCode)
+                    : '';
+
+                $this->respond($data, $statusCode)->send();
+
+                if (ENVIRONMENT !== 'testing') {
+                    // @codeCoverageIgnoreStart
+                    exit($exitCode);
+                    // @codeCoverageIgnoreEnd
+                }
+
+                return;
+            }
+        }
+
+        // Determine possible directories of error views
+        $addPath = ($request instanceof IncomingRequest ? 'html' : 'cli') . DIRECTORY_SEPARATOR;
+        $path    = $this->viewPath . $addPath;
+        $altPath = rtrim((new Paths())->viewDirectory, '\\/ ')
+            . DIRECTORY_SEPARATOR . 'errors' . DIRECTORY_SEPARATOR . $addPath;
+
+        // Determine the views
+        $view    = $this->determineView($exception, $path);
+        $altView = $this->determineView($exception, $altPath);
+
+        // Check if the view exists
+        $viewFile = null;
+        if (is_file($path . $view)) {
+            $viewFile = $path . $view;
+        } elseif (is_file($altPath . $altView)) {
+            $viewFile = $altPath . $altView;
+        }
+
+        // Displays the HTML or CLI error code.
+        $this->render($exception, $statusCode, $viewFile);
+
+        if (ENVIRONMENT !== 'testing') {
+            // @codeCoverageIgnoreStart
+            exit($exitCode);
+            // @codeCoverageIgnoreEnd
+        }
+    }
+
+    /**
+     * Determines the view to display based on the exception thrown,
+     * whether an HTTP or CLI request, etc.
+     *
+     * @return string The filename of the view file to use
+     */
+    protected function determineView(Throwable $exception, string $templatePath): string
+    {
+        // Production environments should have a custom exception file.
+        $view = 'production.php';
+
+        if (str_ireplace(['off', 'none', 'no', 'false', 'null'], '', ini_get('display_errors'))) {
+            $view = 'error_exception.php';
+        }
+
+        // 404 Errors
+        if ($exception instanceof PageNotFoundException) {
+            return 'error_404.php';
+        }
+
+        $templatePath = rtrim($templatePath, '\\/ ') . DIRECTORY_SEPARATOR;
+
+        // Allow for custom views based upon the status code
+        if (is_file($templatePath . 'error_' . $exception->getCode() . '.php')) {
+            return 'error_' . $exception->getCode() . '.php';
+        }
+
+        return $view;
+    }
+}

system/Debug/ExceptionHandlerInterface.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Debug;
+
+use CodeIgniter\HTTP\RequestInterface;
+use CodeIgniter\HTTP\ResponseInterface;
+use Throwable;
+
+interface ExceptionHandlerInterface
+{
+    /**
+     * Determines the correct way to display the error.
+     *
+     * @return void
+     */
+    public function handle(
+        Throwable $exception,
+        RequestInterface $request,
+        ResponseInterface $response,
+        int $statusCode,
+        int $exitCode
+    );
+}

tests/system/Debug/ExceptionHandlerTest.php

@@ -0,0 +1,143 @@
+<?php
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Debug;
+
+use CodeIgniter\Exceptions\PageNotFoundException;
+use CodeIgniter\Test\CIUnitTestCase;
+use CodeIgniter\Test\StreamFilterTrait;
+use Config\Exceptions as ExceptionsConfig;
+use Config\Services;
+use RuntimeException;
+
+/**
+ * @internal
+ *
+ * @group Others
+ */
+final class ExceptionHandlerTest extends CIUnitTestCase
+{
+    use StreamFilterTrait;
+
+    private ExceptionHandler $handler;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->handler = new ExceptionHandler(new ExceptionsConfig());
+    }
+
+    public function testDetermineViewsPageNotFoundException(): void
+    {
+        $determineView = $this->getPrivateMethodInvoker($this->handler, 'determineView');
+
+        $exception    = PageNotFoundException::forControllerNotFound('Foo', 'bar');
+        $templatePath = APPPATH . 'Views/errors/html';
+        $viewFile     = $determineView($exception, $templatePath);
+
+        $this->assertSame('error_404.php', $viewFile);
+    }
+
+    public function testDetermineViewsRuntimeException(): void
+    {
+        $determineView = $this->getPrivateMethodInvoker($this->handler, 'determineView');
+
+        $exception    = new RuntimeException('Exception');
+        $templatePath = APPPATH . 'Views/errors/html';
+        $viewFile     = $determineView($exception, $templatePath);
+
+        $this->assertSame('error_exception.php', $viewFile);
+    }
+
+    public function testDetermineViewsRuntimeExceptionCode404(): void
+    {
+        $determineView = $this->getPrivateMethodInvoker($this->handler, 'determineView');
+
+        $exception    = new RuntimeException('foo', 404);
+        $templatePath = APPPATH . 'Views/errors/html';
+        $viewFile     = $determineView($exception, $templatePath);
+
+        $this->assertSame('error_404.php', $viewFile);
+    }
+
+    public function testCollectVars(): void
+    {
+        $collectVars = $this->getPrivateMethodInvoker($this->handler, 'collectVars');
+
+        $vars = $collectVars(new RuntimeException('This.'), 404);
+
+        $this->assertIsArray($vars);
+        $this->assertCount(7, $vars);
+
+        foreach (['title', 'type', 'code', 'message', 'file', 'line', 'trace'] as $key) {
+            $this->assertArrayHasKey($key, $vars);
+        }
+    }
+
+    public function testHandleWebPageNotFoundExceptionDoNotAcceptHTML(): void
+    {
+        $exception = PageNotFoundException::forControllerNotFound('Foo', 'bar');
+
+        $request  = Services::incomingrequest(null, false);
+        $response = Services::response(null, false);
+        $response->pretend();
+
+        ob_start();
+        $this->handler->handle($exception, $request, $response, 404, EXIT_ERROR);
+        $output = ob_get_clean();
+
+        $json = json_decode($output);
+        $this->assertSame(PageNotFoundException::class, $json->title);
+        $this->assertSame(PageNotFoundException::class, $json->type);
+        $this->assertSame(404, $json->code);
+        $this->assertSame('Controller or its method is not found: Foo::bar', $json->message);
+    }
+
+    public function testHandleWebPageNotFoundExceptionAcceptHTML(): void
+    {
+        $exception = PageNotFoundException::forControllerNotFound('Foo', 'bar');
+
+        $request = Services::incomingrequest(null, false);
+        $request->setHeader('accept', 'text/html');
+        $response = Services::response(null, false);
+        $response->pretend();
+
+        ob_start();
+        $this->handler->handle($exception, $request, $response, 404, EXIT_ERROR);
+        $output = ob_get_clean();
+
+        $this->assertStringContainsString('<title>404 - Page Not Found</title>', $output);
+    }
+
+    public function testHandleCLIPageNotFoundException(): void
+    {
+        $exception = PageNotFoundException::forControllerNotFound('Foo', 'bar');
+
+        $request = Services::clirequest(null, false);
+        $request->setHeader('accept', 'text/html');
+        $response = Services::response(null, false);
+        $response->pretend();
+
+        $this->handler->handle($exception, $request, $response, 404, EXIT_ERROR);
+
+        $this->assertStringContainsString(
+            'ERROR: 404',
+            $this->getStreamFilterBuffer()
+        );
+        $this->assertStringContainsString(
+            'Controller or its method is not found: Foo::bar',
+            $this->getStreamFilterBuffer()
+        );
+
+        $this->resetStreamFilterBuffer();
+    }
+}