Improve SmartExceptionHandler fallbacks and templates; update tests/docs, PHPUnit config, and gitignore

Author: KolesnikovKirill

.gitignore

@@ -1,9 +1,10 @@
 .idea
 .vscode
 .phpunit.result.cache
+.phpunit.cache
 build
 vendor
 phpunix.xml
 composer.lock
 composer.local.json
-composer.local.lock
+composer.local.lock

CHANGELOG.md

@@ -2,7 +2,20 @@
 
 All notable changes to this package are documented in this file.
 
-## [1.1.0] — 2025-11-16
+## [1.2.0] - 2026-01-02
+
+### Changed
+
+-   Debug mode now rethrows view-renderer errors instead of swallowing them.
+-   Plain-text fallback no longer exposes exception details.
+-   HTTP status codes are normalized to the 100-599 range.
+-   View renderer callables are normalized to closures.
+-   Template base path is configurable via constructor.
+-   Status template file tests now use a temp directory.
+-   README updated with behavior notes and template path example.
+-   PHPUnit configuration migrated; .phpunit.cache ignored.
+
+## [1.1.0] - 2025-11-16
 
 ### Changed
 
@@ -11,17 +24,17 @@ All notable changes to this package are documented in this file.
 -   Consistent message generation style: strict matching of the HTTP code with predefined text is used.
 -   Updated the footer in the template (Codemonster Errors).
 
-## [1.0.0] — 2025-11-10
+## [1.0.0] - 2025-11-10
 
 ### Added
 
--   Base interface `ExceptionHandlerInterface`
+-   Base interface `ExceptionHandlerInterface`.
 -   `SmartExceptionHandler` class with support for:
--   Automatic HTTP status detection (404, 500, 401, etc.)
--   Debug mode (`debug.php`) and production mode (`generic.php`)
--   Fallback logic for template errors
--   Works without dependence on `View` (via custom `callable $viewRenderer`)
+-   Automatic HTTP status detection (404, 500, 401, etc.).
+-   Debug mode (`debug.php`) and production mode (`generic.php`).
+-   Fallback logic for template errors.
+-   Works without dependence on `View` (via custom `callable $viewRenderer`).
 -   Base HTML templates:
--   `resources/views/errors/generic.php`
--   `resources/views/errors/debug.php`
--   Full unit test coverage (`PHPUnit 9.6–12.0`)
+-   `resources/views/errors/generic.php`.
+-   `resources/views/errors/debug.php`.
+-   Full unit test coverage (PHPUnit 9.6-12.0).

README.md

@@ -7,22 +7,20 @@
 
 Universal package for handling exceptions and HTTP errors.
 
-## 📦 Installation
+## Installation
 
 ```bash
 composer require codemonster-ru/errors
 ```
 
-## 🚀 Quick Start
+## Quick Start
 
 It can be used as part of a framework or on its own in any PHP project.
 
 ### Example 1. Minimal use
 
 ```php
-use Codemonster\Errors\Contracts\ExceptionHandlerInterface;
 use Codemonster\Errors\Handlers\SmartExceptionHandler;
-use Codemonster\Http\Response;
 
 require __DIR__ . '/vendor/autoload.php';
 
@@ -65,26 +63,49 @@ try {
 }
 ```
 
-## 🧱 Template structure
+## Template structure
 
 ```
 resources/views/errors/
-├── generic.php # error page for production
-└── debug.php # debug page for developers
+- generic.php # error page for production
+- debug.php # debug page for developers
+- 404.php # optional, per-status page
+- 500.php # optional, per-status page
 ```
 
-## 🧪 Testing
+Any 3-digit HTTP status file will be used when present.
+You can override the template base path with the third constructor argument.
+Constructor: `new SmartExceptionHandler(?callable $viewRenderer = null, bool $debug = false, ?string $templatePath = null)`
+
+Example:
+
+```php
+$handler = new SmartExceptionHandler(
+    viewRenderer: null,
+    debug: false,
+    templatePath: __DIR__ . '/resources/views/errors'
+);
+```
+
+## Behavior
+
+-   Uses `errors.debug` when `debug: true`.
+-   Uses `errors.<status>` when a status-specific template exists.
+-   Falls back to `errors.generic`, then to a plain-text response.
+-   In debug mode, renderer exceptions are rethrown.
+
+## Testing
 
 You can run tests with the command:
 
 ```bash
 composer test
 ```
 
-## 👨‍💻 Author
+## Author
 
 [**Kirill Kolesnikov**](https://github.com/KolesnikovKirill)
 
-## 📜 License
+## License
 
 [MIT](https://github.com/codemonster-ru/errors/blob/main/LICENSE)

phpunit.xml.dist

@@ -1,30 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
-    bootstrap="vendor/autoload.php"
-    colors="true"
-    stopOnFailure="false"
-    cacheResult="true"
-    executionOrder="depends,defects"
-    beStrictAboutTestsThatDoNotTestAnything="true"
->
-
-    <testsuites>
-        <testsuite name="Codemonster Errors Test Suite">
-            <directory>tests</directory>
-        </testsuite>
-    </testsuites>
-
-    <php>
-        <env name="APP_ENV" value="testing" />
-        <env name="APP_DEBUG" value="true" />
-        <env name="APP_NAME" value="Codemonster Errors" />
-    </php>
-
-    <logging>
-        <junit outputFile="build/test-results/junit.xml" />
-        <text outputFile="build/test-results/test.log" />
-    </logging>
-
-</phpunit>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/12.4/phpunit.xsd" bootstrap="vendor/autoload.php" colors="true" stopOnFailure="false" cacheResult="true" executionOrder="depends,defects" beStrictAboutTestsThatDoNotTestAnything="true" cacheDirectory=".phpunit.cache">
+  <testsuites>
+    <testsuite name="Codemonster Errors Test Suite">
+      <directory>tests</directory>
+    </testsuite>
+  </testsuites>
+  <php>
+    <env name="APP_ENV" value="testing"/>
+    <env name="APP_DEBUG" value="true"/>
+    <env name="APP_NAME" value="Codemonster Errors"/>
+  </php>
+  <logging>
+    <junit outputFile="build/test-results/junit.xml"/>
+  </logging>
+</phpunit>

src/Handlers/SmartExceptionHandler.php

@@ -4,17 +4,23 @@
 
 use Codemonster\Errors\Contracts\ExceptionHandlerInterface;
 use Codemonster\Http\Response;
+use Closure;
 use Throwable;
 
 class SmartExceptionHandler implements ExceptionHandlerInterface
 {
-    protected $viewRenderer;
+    protected ?Closure $viewRenderer;
     protected bool $debug;
+    protected string $templatePath;
 
-    public function __construct(?callable $viewRenderer = null, bool $debug = false)
+    /**
+     * Order: errors.debug (debug=true), errors.{status}, errors.generic, fallback plain-text.
+     */
+    public function __construct(?callable $viewRenderer = null, bool $debug = false, ?string $templatePath = null)
     {
-        $this->viewRenderer = $viewRenderer;
+        $this->viewRenderer = $viewRenderer ? Closure::fromCallable($viewRenderer) : null;
         $this->debug = $debug;
+        $this->templatePath = $templatePath ?? (dirname(__DIR__, 2) . '/resources/views/errors');
     }
 
     public function handle(Throwable $e): Response
@@ -26,8 +32,12 @@ public function handle(Throwable $e): Response
             $status = $e->getStatusCode();
         }
 
+        if (!is_int($status) || $status < 100 || $status > 599) {
+            $status = 500;
+        }
+
         if ($this->debug) {
-            return $this->renderTemplate('errors.debug', ['exception' => $e], $status) ?? $this->fallbackDebug($e);
+            return $this->renderTemplate('errors.debug', ['exception' => $e], $status) ?? $this->fallbackDebug($e, $status);
         }
 
         return $this->renderTemplate(
@@ -55,21 +65,28 @@ protected function renderTemplate(string $template, array $data, int $status): ?
     {
         if ($this->viewRenderer) {
             try {
-                $html = call_user_func($this->viewRenderer, $template, $data);
+                $html = ($this->viewRenderer)($template, $data);
 
                 if ($html) {
                     return new Response($html, $status, ['Content-Type' => 'text/html']);
                 }
-            } catch (Throwable) {
+            } catch (Throwable $renderError) {
+                if ($this->debug) {
+                    throw $renderError;
+                }
             }
         }
 
-        $basePath = dirname(__DIR__, 2) . '/resources/views/errors';
+        $basePath = $this->templatePath;
         $fileMap = [
             'errors.generic' => "$basePath/generic.php",
             'errors.debug'   => "$basePath/debug.php",
         ];
 
+        if (!isset($fileMap[$template]) && preg_match('/^errors\.(\d{3})$/', $template, $matches)) {
+            $fileMap[$template] = sprintf('%s/%s.php', $basePath, $matches[1]);
+        }
+
         if (isset($fileMap[$template]) && is_file($fileMap[$template])) {
             ob_start();
             extract($data, EXTR_SKIP);
@@ -87,17 +104,14 @@ protected function renderTemplate(string $template, array $data, int $status): ?
     protected function fallbackPlain(Throwable $e, int $status): Response
     {
         $content = sprintf(
-            "HTTP %d %s\nin %s:%d",
-            $status,
-            $e->getMessage(),
-            $e->getFile(),
-            $e->getLine()
+            "HTTP %d\nAn unexpected error occurred.",
+            $status
         );
 
         return new Response($content, $status, ['Content-Type' => 'text/plain']);
     }
 
-    protected function fallbackDebug(Throwable $e): Response
+    protected function fallbackDebug(Throwable $e, int $status): Response
     {
         $content = sprintf(
             "[%s] %s\nin %s:%d\n\n%s",
@@ -108,6 +122,6 @@ protected function fallbackDebug(Throwable $e): Response
             $e->getTraceAsString()
         );
 
-        return new Response($content, 500, ['Content-Type' => 'text/plain']);
+        return new Response($content, $status, ['Content-Type' => 'text/plain']);
     }
 }

tests/SmartExceptionHandlerTest.php

@@ -51,18 +51,53 @@ public function getStatusCode(): int
         self::assertSame(404, $response->getStatusCode());
     }
 
-    public function testFallbackDebugOutputWhenRendererFails(): void
+    public function testRendersStatusTemplateFromFileWhenPresent(): void
+    {
+        $basePath = sys_get_temp_dir() . '/codemonster-errors-' . uniqid('', true);
+        $templatePath = $basePath . '/404.php';
+
+        if (!is_dir($basePath)) {
+            mkdir($basePath, 0777, true);
+        }
+
+        try {
+            file_put_contents(
+                $templatePath,
+                "<?php echo 'status-template-' . (int) (\$status ?? 0);"
+            );
+
+            $exception = new class('Page missing', 404) extends RuntimeException {
+                public function getStatusCode(): int
+                {
+                    return 404;
+                }
+            };
+
+            $handler = new SmartExceptionHandler(null, false, $basePath);
+            $response = $handler->handle($exception);
+
+            self::assertSame(404, $response->getStatusCode());
+            self::assertStringContainsString('status-template-404', (string)$response);
+        } finally {
+            if (is_file($templatePath)) {
+                unlink($templatePath);
+            }
+
+            if (is_dir($basePath)) {
+                rmdir($basePath);
+            }
+        }
+    }
+
+    public function testThrowsWhenRendererFailsInDebugMode(): void
     {
         $renderer = static function (): string {
             throw new RuntimeException('View failed');
         };
 
         $handler = new SmartExceptionHandler($renderer, true);
-        $response = $handler->handle(new RuntimeException('Crash'));
-
-        self::assertInstanceOf(Response::class, $response);
-        self::assertSame(500, $response->getStatusCode());
-        self::assertStringContainsString('<html', (string)$response);
-        self::assertStringContainsString('Crash', (string)$response);
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('View failed');
+        $handler->handle(new RuntimeException('Crash'));
     }
 }