Errata

Exceptionally safe error handling for JSON APIs using API Problem (RFC 9457) objects.

Installation

composer require errata/errata

Quick start

ProblemMiddleware is a PSR-15 middleware. Register it as the outermost middleware so it sees everything the rest of the stack throws.

use Errata\Middleware\ProblemMiddleware;
use Errata\ThrowableTransformer;

// Configure which throwables/exceptions map to which problems,
// and what extensions should be enabled.
$transformer = new ThrowableTransformer();

$middleware = new ProblemMiddleware(
    $responseFactory,    // any PSR-17 ResponseFactoryInterface
    $streamFactory,      // any PSR-17 StreamFactoryInterface
    $transformer,        // optional throwable transformer
    $logger,             // optional PSR-3 logger
);

A response returned by the inner stack passes through unchanged. When the inner stack throws, the throwable is converted to a problem and returned as an application/problem+json response.

Documentation

• Problems covers the Problem document and the fixed-status HTTP problems.
• Transforming Throwables covers how a Throwable becomes a problem and the built-in extensions.
• Middleware covers the middleware's behavior, failure fallback, and logging.

Development

This project uses Mago for lint, formatting, and static analysis.

composer run fix       # automatically fix lint, analysis, and formatting issues
composer run format    # format source code
composer run check     # check style
composer run lint      # lint code
composer run analyze   # static analysis
composer run test      # unit testing with 100% coverage enforced
composer run verify    # run all verifications (check + lint + analyze + test)