PHPackages                             compono-kit/error-handlers - 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. [Utility & Helpers](/categories/utility)
4. /
5. compono-kit/error-handlers

ActiveLibrary[Utility & Helpers](/categories/utility)

compono-kit/error-handlers
==========================

Interfaces for error handlers and an error handler delegator

1.0.0(today)00proprietaryPHPPHP >=8.1

Since Jun 22Pushed todayCompare

[ Source](https://github.com/compono-kit/error-handlers)[ Packagist](https://packagist.org/packages/compono-kit/error-handlers)[ RSS](/packages/compono-kit-error-handlers/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (1)Versions (3)Used By (0)

ErrorHandlers
=============

[](#errorhandlers)

Provides a common interface for error handlers, a delegator that routes events to multiple handlers based on minimum severity, and a trait to inject error handlers into your own classes.

Installation
------------

[](#installation)

```
composer require compono-kit/error-handlers
```

Concepts
--------

[](#concepts)

### `HandlesErrors` — the interface every handler implements

[](#handleserrors--the-interface-every-handler-implements)

Any concrete handler (Sentry, file logger, Slack alert, …) implements this interface:

```
use ComponoKit\ErrorHandlers\Interfaces\HandlesErrors;
use ComponoKit\ErrorHandlers\Models\Types\ErrorLevel;

class FileErrorHandler implements HandlesErrors
{
    public function install(): void
    {
        // register global exception / error handlers here
    }

    public function exception(\Throwable $exception, string $message = '', array $context = [], array $tags = []): void
    {
        file_put_contents('error.log', $exception->getMessage() . PHP_EOL, FILE_APPEND);
    }

    public function warning(string $message, array $context = [], array $tags = []): void { /* ... */ }
    public function error(string $message, array $context = [], array $tags = []): void { /* ... */ }
    public function critical(string $message, array $context = [], array $tags = []): void { /* ... */ }
    public function alert(string $message, array $context = [], array $tags = []): void { /* ... */ }
    public function emergency(string $message, array $context = [], array $tags = []): void { /* ... */ }
}
```

### `ErrorHandlerDelegator` — route events to multiple handlers

[](#errorhandlerdelegator--route-events-to-multiple-handlers)

Register each handler with a **minimum severity level**. The handler is only called for events at or above that level.

```
use ComponoKit\ErrorHandlers\ErrorHandlerDelegator;
use ComponoKit\ErrorHandlers\Models\Types\ErrorLevel;

$delegator = new ErrorHandlerDelegator();

// FileErrorHandler receives everything from WARNING upwards
$delegator->addErrorHandler(new FileErrorHandler(), ErrorLevel::WARNING);

// SmsAlertHandler only receives EMERGENCY events
$delegator->addErrorHandler(new SmsAlertHandler(), ErrorLevel::EMERGENCY);

// Activates all registered handlers (e.g. registers global exception handlers)
$delegator->install();
```

Now when you report events:

```
// Only FileErrorHandler is called (WARNING ≥ WARNING, EMERGENCY > WARNING)
$delegator->warning('Disk space below 10 %', ['free_mb' => '80']);

// Both handlers are called (WARNING ≥ WARNING, EMERGENCY ≥ EMERGENCY)
$delegator->emergency('Database unreachable');
```

Severity order from lowest to highest: `WARNING → ERROR → CRITICAL → ALERT → EMERGENCY`

#### `$context` and `$tags`

[](#context-and-tags)

Both parameters are `array` — flat maps of string keys to string values. Do not pass nested arrays, objects, or other complex types, as concrete handler implementations (Sentry, log files, etc.) cannot reliably serialize them.

```
// correct
$delegator->error('Payment failed', ['order_id' => '42', 'currency' => 'EUR'], ['checkout']);

// incorrect — nested array and object will be rejected by handlers
$delegator->error('Payment failed', ['order' => $orderObject, 'meta' => ['a' => 'b']]);
```

#### Exceptions with an explicit severity

[](#exceptions-with-an-explicit-severity)

`exception()` accepts an optional `ErrorLevel` parameter (defaults to `EMERGENCY`). This controls which handlers receive the event — useful when not every exception is critical:

```
// Only reaches handlers registered at WARNING or ERROR — not the SMS alert
$delegator->exception($exception, 'Validation failed');

// Reaches all handlers (default behaviour)
$delegator->exception($exception, 'Payment provider unreachable');
```

### `ErrorHandlerAware` + `ProvidingErrorHandler` — inject a handler into your services

[](#errorhandleraware--providingerrorhandler--inject-a-handler-into-your-services)

Use the interface and trait to make any class accept an error handler. If no handler is injected, a `NullErrorHandler` is used silently — no errors, no crashes.

```
use ComponoKit\ErrorHandlers\Interfaces\ErrorHandlerAware;
use ComponoKit\ErrorHandlers\Traits\ProvidingErrorHandler;

class OrderService implements ErrorHandlerAware
{
    use ProvidingErrorHandler;

    public function placeOrder(string $orderId): void
    {
        try {
            // ...
        } catch (\Throwable $exception) {
            $this->getErrorHandler()->exception($exception, 'Order failed', ['order_id' => $orderId]);
        }
    }
}
```

Without injecting a handler the service works silently:

```
$service = new OrderService();
$service->placeOrder('order-42'); // exceptions are swallowed by NullErrorHandler
```

Inject the delegator when you want real reporting:

```
$service->useErrorHandler($delegator);
$service->placeOrder('order-42'); // exceptions now reach all registered handlers
```

NullErrorHandler
----------------

[](#nullerrorhandler)

`NullErrorHandler` is a no-op implementation of `HandlesErrors`. It is the default handler in `ProvidingErrorHandler` and can also be used explicitly in tests or environments where error reporting is not needed.

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

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

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8b4875ebadf24ddeae09bd59c44c9a86a61c3d3892fe1d4a264ad167b6d230cc?d=identicon)[Hansel23](/maintainers/Hansel23)

---

Top Contributors

[![Hansel23](https://avatars.githubusercontent.com/u/15147826?v=4)](https://github.com/Hansel23 "Hansel23 (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/compono-kit-error-handlers/health.svg)

```
[![Health](https://phpackages.com/badges/compono-kit-error-handlers/health.svg)](https://phpackages.com/packages/compono-kit-error-handlers)
```

###  Alternatives

[spatie/enum

PHP Enums

84731.4M74](/packages/spatie-enum)

PHPackages © 2026

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