PHPackages                             componenta/error-handler - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. componenta/error-handler

ActiveLibrary[Logging & Monitoring](/categories/logging)

componenta/error-handler
========================

HTTP and CLI error handling for Componenta

v1.0.0(1mo ago)087MITPHPPHP ^8.4

Since Jun 16Pushed 1mo agoCompare

[ Source](https://github.com/componenta/error-handler)[ Packagist](https://packagist.org/packages/componenta/error-handler)[ RSS](/packages/componenta-error-handler/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (8)Versions (2)Used By (7)

Componenta Error Handler
========================

[](#componenta-error-handler)

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

[](#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
----------------

[](#related-packages)

PackageWhy it matters here`componenta/http`Provides HTTP exception types; PSR request/response integration is implemented by the HTTP error handler and app packages.`componenta/pipeline`Usually runs `ErrorHandlerMiddleware` as the outermost HTTP middleware.`componenta/event`Can be used for error reporting listeners.`psr/log`Fits logging listeners and reporters.`componenta/config`Registers default HTTP/CLI handlers, renderers, and reporters.`componenta/http-psr-nyholm`, `componenta/http-psr-diactoros`, `componenta/http-psr-guzzle`, or `componenta/http-psr-slim`Registers the concrete PSR-17 factories used by HTTP response generation.What It Provides
----------------

[](#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
----------

[](#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
---------

[](#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
---------

[](#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:

PackageRendererTypical use[`componenta/error-renderer-plates`](../error-renderer-plates/README.md)`PlatesRenderer`Safe or custom HTML error pages rendered with League Plates templates.[`componenta/error-renderer-whoops`](../error-renderer-whoops/README.md)`WhoopsRenderer`Detailed development error pages through Whoops.[`componenta/error-renderer-symfony`](../error-renderer-symfony/README.md)`SymfonyRenderer`Symfony error page rendering adapted to `ErrorRendererInterface`.[`componenta/error-renderer-ignition`](../error-renderer-ignition/README.md)`IgnitionRenderer`Spatie Ignition development error pages.[`componenta/error-renderer-collision`](../error-renderer-collision/README.md)`CollisionRenderer`Rich CLI error output through Collision.Contexts
--------

[](#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
---------

[](#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
---------------

[](#di-registration)

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

Important config keys:

KeyPurpose`ConfigKey::HTTP_FALLBACK_GENERATOR`Service id for the fallback `HttpErrorResponseGeneratorInterface`.`ConfigKey::HTTP_RENDERER`Renderer used by the default HTTP response generator.`ConfigKey::HTTP_GENERATORS`Ordered service ids for specialized HTTP response generators.`ConfigKey::HTTP_LISTENERS`HTTP error listeners.`ConfigKey::CLI_FALLBACK_HANDLER`CLI fallback renderer/handler.`ConfigKey::CLI_RENDERER`CLI renderer.`ConfigKey::CLI_LISTENERS`CLI error listeners.`ConfigKey::ERROR_REPORTER`Reporter service.`ConfigKey::ERROR_ID_GENERATOR`Error id generator service.`ConfigKey::ERROR_LEVEL`Error level handled by `ErrorHandlerMiddleware`.If no `ConfigKey::HTTP_FALLBACK_GENERATOR` is configured, the default HTTP handler requires `Psr\Http\Message\ResponseFactoryInterface` in the container.

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance91

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

43d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/20490712?v=4)[Andrey Shelamkoff](/maintainers/Shelamkoff)[@Shelamkoff](https://github.com/Shelamkoff)

---

Top Contributors

[![Shelamkoff](https://avatars.githubusercontent.com/u/20490712?v=4)](https://github.com/Shelamkoff "Shelamkoff (1 commits)")

### Embed Badge

![Health badge](/badges/componenta-error-handler/health.svg)

```
[![Health](https://phpackages.com/badges/componenta-error-handler/health.svg)](https://phpackages.com/packages/componenta-error-handler)
```

###  Alternatives

[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[cakephp/cakephp

The CakePHP framework

8.8k19.5M1.8k](/packages/cakephp-cakephp)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k17](/packages/tempest-framework)[typo3/cms-core

TYPO3 CMS Core

3713.2M5.2k](/packages/typo3-cms-core)[getgrav/grav

Modern, Crazy Fast, Ridiculously Easy and Amazingly Powerful Flat-File CMS

15.6k86.4k1](/packages/getgrav-grav)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)