README

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

composer require compono-kit/error-handlers

Concepts

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

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

Both parameters are array<string, string> — 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

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

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