README

Capture, buffer, aggregate, and render errors. Every event is recorded; emit channels (PSR log, render, terminate) apply filters and priority separately.

Requires PHP 8.4+.

Install

composer require northrook/error-handler

Quick start

use Northrook\ErrorHandler;
use Northrook\ErrorHandler\ErrorHandlerConfig;
use Northrook\ErrorHandler\ErrorLevelMask;
use Psr\Log\LoggerInterface;

$handler = ErrorHandler::register(
    logger: $psrLogger,                    // optional; defaults to NullLogger
    throwAt: ErrorLevelMask::Standard,     // optional; see Throw mask
    config: new ErrorHandlerConfig(debug: true),
);

// Uncaught exceptions and fatals are handled automatically once installed.

register() builds the singleton and, by default, installs global error / exception / shutdown handlers. Pass install: false to construct without wiring globals, then call $handler->install() when ready.

Design

Pipeline (current):

PHP error / throwable / box probe
        ↓
  ErrorBuffer (always)
        ↓
  Fingerprint → Aggregator (count + highest priority)
        ↓
  Route: Critical → log now; else queue until shutdown flush
        ↓
  handle() also renders + exit(1)

Registration & lifecycle

ErrorHandler::register()

ErrorHandler::register(
    null|LoggerInterface $logger = null,
    null|ErrorRendererInterface $renderer = null,
    null|int|ErrorLevelMask $throwAt = null,
    bool $install = true,
    null|ErrorHandlerConfig $config = null,
): ErrorHandler

Install / uninstall / reset

$handler->install();    // set_error_handler, set_exception_handler, register_shutdown_function
$handler->uninstall();  // restore previous handlers
$handler->reset();      // uninstall (if installed), clear buffer + aggregator, drop singleton

Shutdown always flushes pending aggregates to the logger first, then handles fatal last-errors.

Configuration

use Northrook\Contracts\RenderStrategy;
use Northrook\ErrorHandler\ErrorHandlerConfig;

new ErrorHandlerConfig(
    debug: true,                          // default: AppEnv::isDebug()
    renderStrategy: RenderStrategy::AUTO, // honored by ReportFactory / dumps
    colorPalette: null,                   // optional ColorPalette override
);

• debug — when true, context['dumps'] are turned into VarDump bags for CLI/HTML. When false, dumps are ignored.
• renderStrategy — passed into dump rendering (AUTO picks CLI vs HTML by SAPI).

Throw mask (ErrorLevelMask)

Controls which PHP error types the global handler promotes to ErrorException. Independent of priority / logging.

use Northrook\ErrorHandler\ErrorLevelMask;

ErrorHandler::register(throwAt: ErrorLevelMask::Standard);
ErrorHandler::register(throwAt: E_USER_WARNING | E_USER_ERROR); // raw int also fine

Silenced errors (error_reporting masks the type, or @) are always buffered and aggregated as Noise; they never throw.

Scoped probes — box()

Failsafe: catch PHP errors inside a callback, keep going. Never throws from the scoped handler.

$result = $handler->box(
    fn () => $cache->warm($key),
    // optional: EventPriority::Action,
);

if ($handler->lastBoxError() !== null) {
    // inspect RuntimeError; process continues
}

lastBoxError() is the last RuntimeError from the most recent box(); lastError() is the last entry in the global buffer.

Reports — report() vs handle()

report(Throwable $e, array $context = []): ErrorReport

Builds a structured ErrorReport (reference, snapshot, stack, previous chain, context, dumps, PHP errors). Does not exit.

Default priority: Action. Override with reserved context key:

$report = $handler->report($e, [
    'priority' => EventPriority::Critical, // or 'Critical' / 'critical'
    'orderId'  => $orderId,
    'dumps'    => [
        'cart' => $cart,
        'user' => $user,
    ],
]);

echo $handler->renderer->json->render($report); // or cli / html

Reserved keys (stripped from stored context):

handle(Throwable $e): never

Forces Critical, aggregates, logs immediately, sets HTTP 500 (when not CLI and headers not sent), renders via the composite renderer, then exit(1).

Uncaught exceptions go through handle() (except under PHPUnit, where they are rethrown).

Priority & aggregation

EventPriority

Defaults by path:

Repeats of the same fingerprint elevate to the highest priority seen and bump count.

Fingerprint

Stable xxh32 of class|phpType + file + line + message — used for aggregation. Separate from the per-instance report reference (error-{xxh32}).

Standing list & flush

$handler->actionables();              // Action+ entries this request
$handler->aggregator()->all();        // every fingerprint
$handler->flushPendingAggregates();   // emit queued Noise/Action now (also called on shutdown)

Each emit is one PSR log line per fingerprint:

Context includes fingerprint, priority, count, class, reference (when a report exists), firstSeen, lastSeen.

Buffer inspection

$buffer = $handler->errors();           // ErrorBufferInterface (shared)
$buffer->all();
$buffer->last();
$mark = $buffer->mark();
$since = $buffer->since($mark);

Everything that hits the global or scoped handlers is recorded here, including silenced notices.

Renderers

ErrorRenderer picks CLI vs HTML by SAPI. JSON is available explicitly.

Source highlighting and var dumps come from northrook/php-debug — this package wires them in; it does not reimplement them.

Composite construction (optional overrides):

use Northrook\ErrorHandler\ErrorRenderer;
use Northrook\ErrorHandler\Renderer\CliRenderer;
use Northrook\ErrorHandler\Renderer\HtmlRenderer;
use Northrook\ErrorHandler\Renderer\JsonRenderer;

$renderer = new ErrorRenderer(
    cli: new CliRenderer(),
    html: new HtmlRenderer(new ErrorHandlerConfig(debug: true)),
    json: new JsonRenderer(),
);

If a backend renderer itself throws, a dependency-light disaster fallback is printed and the failure is logged at critical.

Typed exception meta

ReportFactory attaches snapshot meta for known contract exceptions (e.g. filesystem path, curl URL). Extend buildMeta() as more types land in contracts.

Demos

From the package root:

php index.php              # list demos
php index.php exception    # uncaught → handle() view
php index.php box          # failsafe probe
php index.php dumps        # context dumps in CLI/HTML
php index.php aggregate    # Noise counts + Action standing list + flush

# Browser
php -S localhost:8080 index.php
# open /?demo=exception

Tests & static analysis

composer test
composer phpstan

Not yet implemented

Deferred (see PLAN.md): SilencePolicy / screamAt, ReportVerbosity Safe redaction, RuntimeMode presets, signature rules, SQLite/file persistence, WTHH disaster file, notification delivery.