codemonster-ru/errors

Universal exception and HTTP error handling package for PHP applications. Developed for the Codemonster ecosystem (Annabel framework).

v1.2.0 2026-01-02 17:04 UTC

Requires

• php: >=8.2
• codemonster-ru/http: ^2.0

Requires (Dev)

• phpunit/phpunit: ^9.6 || ^10.5 || ^11.0 || ^12.0

MIT

• Kirill Kolesnikov

• framework
• php
• http
• errors
• exceptions
• handler
• codemonster
• annabel

README

Universal package for handling exceptions and HTTP errors.

Installation

composer require codemonster-ru/errors

Quick Start

It can be used as part of a framework or on its own in any PHP project.

Example 1. Minimal use

use Codemonster\Errors\Handlers\SmartExceptionHandler;

require __DIR__ . '/vendor/autoload.php';

$handler = new SmartExceptionHandler();

set_exception_handler(function (Throwable $e) use ($handler) {
    $response = $handler->handle($e);

    if (php_sapi_name() !== 'cli') {
        http_response_code($response->getStatusCode());

        echo (string) $response;
    } else {
        fwrite(STDERR, (string) $response . PHP_EOL);
    }
});

throw new RuntimeException('Something went wrong!');

When you run it, you'll get a neat HTML page (or a text fallback in the CLI), with error information and the correct HTTP code.

Example 2. Integration with a View renderer (e.g. from a framework)

use Codemonster\Errors\Handlers\SmartExceptionHandler;
use Codemonster\View\View;

$view = new View(...);
$viewRenderer = fn(string $template, array $data) => $view->render($template, $data);
$handler = new SmartExceptionHandler($viewRenderer, debug: true);

try {
    throw new RuntimeException('Demo error');
} catch (Throwable $e) {
    $response = $handler->handle($e);

    echo $response;
}

Template structure

resources/views/errors/
- generic.php # error page for production
- debug.php # debug page for developers
- 404.php # optional, per-status page
- 500.php # optional, per-status page

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:

$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:

composer test

Author

Kirill Kolesnikov

License

MIT