super-kernel / exception-dispatcher

dev-main 2026-11-01 07:40 UTC

Requires

• php: >=8.4.27 <8.5
• psr/container: ^2.0.2
• super-kernel/annotator: dev-main
• super-kernel/attribute: dev-main
• super-kernel/contract: dev-main

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.95.27
• phpunit/phpunit: ^13.4.5

MIT

Published on Packagist.org on 2026-11-01 07:40 UTC

README

English | 中文文档

SuperKernel Exception Dispatcher

super-kernel/exception-dispatcher provides the DI-ready exception-handler registry and generic dispatcher used by SuperKernel runtime boundaries.

Declaring handlers

A handler is a class carrying #[ExceptionHandler] and implementing Contract\ExceptionHandlerInterface, whose handle(Throwable): void method performs non-protocol exception handling. The Attribute declares the handled Throwable class, Throwable::class by default, and an integer priority, 0 by default. Handlers are resolved from DI; higher priorities run first and equal priorities keep discovery order.

To customize exception output, declare an #[ExceptionHandler(exception: Throwable::class)] handler or replace stdout log formatting through the StdoutLoggerInterface contract.

Dispatching

SuperKernel\Contract\ExceptionDispatcherInterface::dispatch() accepts only a Throwable and returns void. The generic dispatcher invokes every matching handler; a handler matches the declared exception class and its subclasses. A failed handler is fallback-reported and does not prevent a later matching handler from running. If no matching handler completes successfully, the original throwable is written once through SuperKernel\Contract\StdoutLoggerInterface. The dispatcher does not select an HTTP response, process exit, task result, or another protocol action.

Fallback records always contain the complete (string) $throwable, including PHP's file, line, stack, and previous-exception chain, through StdoutLoggerInterface; applications need no configuration for this component.

Use the dispatcher only after the current process's DI container is ready; it provides no handler for failures that occur before then.

Protocol-specific handlers

A protocol component may derive its own Attribute from Attribute\ExceptionHandler and validate its own handler contract. Registry\ExceptionHandlerProvider::getHandlersForAttribute() returns the registrations for one exact Attribute class in priority order, so the generic dispatcher handles only exact #[ExceptionHandler] declarations. ExceptionHandlerRegistration::matches(Throwable $throwable): bool exposes the shared matching rule:

foreach ($handlerProvider->getHandlersForAttribute($attributeClass) as $registration) {
    if ($registration->matches($throwable)) {
        // Apply the protocol's handler contract and response/propagation rules.
    }
}