README

HTTP and CLI error handling for PHP 8.4+ applications.

The package contains the reusable error handling layer. It does not choose a concrete PSR-7/PSR-17 implementation. HTTP applications must register Psr\Http\Message\ResponseFactoryInterface through one of the componenta/http-psr-* integration packages or provide a custom HttpErrorResponseGeneratorInterface.

Installation

composer require componenta/error-handler

The package declares Componenta\Error\ConfigProvider in extra.componenta.config-providers. When componenta/composer-plugin is installed, the provider is added to the generated provider list automatically.

Related Packages

What It Provides

• HTTP and CLI aggregate error handlers.
• Fallback response generator for exceptions not handled by a specialized generator. The generator still requires an explicit PSR-17 ResponseFactoryInterface.
• Error renderers for safe HTML/JSON, JSON, HTML, plain text, null output, and composite rendering.
• Error reporting listeners for logging, monitoring, and notifications.
• Immutable HTTP and CLI contexts.
• PSR-15 middleware for HTTP applications.
• Config provider for framework integration.

HTTP Usage

use Componenta\Error\Handler\HttpErrorHandler;
use Componenta\Error\Http\HttpErrorResponseGenerator;
use Componenta\Error\Http\Middleware\ErrorHandlerMiddleware;
use Psr\Http\Message\ResponseFactoryInterface;

/** @var ResponseFactoryInterface $responseFactory */
$fallback = new HttpErrorResponseGenerator($responseFactory);
$handler = new HttpErrorHandler($fallback);

$middleware = new ErrorHandlerMiddleware($handler);
$response = $middleware->process($request, $next);

Register specialized generators with priorities:

$handler->addGenerator(new NotFoundGenerator($responseFactory), priority: 100);
$handler->addGenerator(new ValidationGenerator($responseFactory), priority: 50);

Higher priority generators are checked first.

Custom generators implement HttpErrorResponseGeneratorInterface:

use Componenta\Error\Context\HttpErrorContextInterface;
use Componenta\Error\ErrorContextInterface;
use Componenta\Error\Http\HttpErrorResponseGeneratorInterface;
use InvalidArgumentException;
use Psr\Http\Message\ResponseInterface;
use Throwable;

final readonly class ValidationErrorResponseGenerator implements HttpErrorResponseGeneratorInterface
{
    public function supports(Throwable $exception, ErrorContextInterface $context): bool
    {
        return $context instanceof HttpErrorContextInterface
            && $exception instanceof InvalidArgumentException;
    }

    public function generate(Throwable $exception, HttpErrorContextInterface $context): ResponseInterface
    {
        // Build and return a PSR-7 response.
    }
}

HttpErrorResponseGenerator resolves the response status once through HttpStatusResolver and writes it to the context as ErrorContextAttribute::HTTP_STATUS_CODE before rendering. The default resolver uses HttpStatusAwareInterface, then an exception code in the 400..599 range, then 500.

CLI Usage

use Componenta\Error\Context\CliContext;
use Componenta\Error\Handler\CliErrorHandler;
use Componenta\Error\Handler\RenderingCliErrorHandler;

$handler = new CliErrorHandler(new RenderingCliErrorHandler());

try {
    $app->run();
} catch (Throwable $exception) {
    $handler->handle($exception, CliContext::fromArgv());
    exit(1);
}

Renderers

Built-in renderers:

• SafeRenderer
• JsonRenderer
• HtmlRenderer
• PrettyPageRenderer
• PlainTextRenderer
• ConsoleErrorRenderer
• NullRenderer
• CompositeErrorRenderer

Fallback generators use safe defaults: HTTP uses SafeRenderer, CLI uses PlainTextRenderer.

Additional renderer integrations live in separate packages:

Contexts

Contexts carry request or command-line information plus arbitrary attributes.

$context = $context->withAttribute('user_id', 123);
$userId = $context->getAttribute('user_id');

Context objects are immutable: withAttribute() and withAttributes() return a new instance.

HttpContext::fromGlobals() does not create PSR-17 factories by itself. Pass a Nyholm\Psr7Server\ServerRequestCreatorInterface when a context must be built from PHP superglobals:

$context = HttpContext::fromGlobals($serverRequestCreator);

Reporting

Register listeners for logging or monitoring:

use Componenta\Error\Event\ErrorEventInterface;
use Componenta\Error\Event\ErrorListener;

$handler->addListener(
    ErrorListener::createFrom(static function (ErrorEventInterface $event): void {
        // log or report $event->exception and $event->context
    }),
    priority: 100,
);

Specific exceptions can be excluded from reporting by class name or predicate.

ErrorReporter accepts a ListenerExceptionPolicy. The default policy swallows listener failures and writes them through error_log(), so error reporting cannot replace the original application exception with a logging failure.

DI Registration

ConfigProvider registers the HTTP/CLI handlers, renderers, reporter, and middleware dependencies needed by Componenta applications.

Important config keys:

If no ConfigKey::HTTP_FALLBACK_GENERATOR is configured, the default HTTP handler requires Psr\Http\Message\ResponseFactoryInterface in the container.