README

A lightweight, dependency-free PSR-15 middleware dispatcher and pipeline for PHP 8+.

Features

• Two dispatch strategies — flat-list Dispatcher and linked-list MiddlewarePipe
• PSR-15 compliant — works with any MiddlewareInterface / RequestHandlerInterface implementation
• Optional PSR-11 container — resolve middleware from any container by class name
• Fluent API — chain add() calls on Dispatcher
• Deep-clone safe — MiddlewarePipe cloning does not share mutable state
• Zero production dependencies beyond the PSR packages

Requirements

Installation

composer require horizom/dispatcher

Concepts

Dispatcher — flat-list strategy

The Dispatcher keeps an ordered array of middlewares and an integer step counter. Calling dispatch() always resets the counter to 0 and calls handle() on the first entry. Each middleware is expected to call $handler->handle($request) to advance to the next step.

[MiddlewareA] → [MiddlewareB] → [TerminalHandler]
     ↓                ↓                ↓
  process()        process()        handle()

MiddlewarePipe — linked-list strategy

The MiddlewarePipeFactory builds an immutable linked list of MiddlewarePipe nodes. Each node holds a reference to the current entry and the next node. The chain is terminated by an EmptyRequestHandler sentinel that throws if reached.

MiddlewarePipe(A) → MiddlewarePipe(B) → MiddlewarePipe(Handler) → EmptyRequestHandler

Usage

Flat-list Dispatcher

use Horizom\Dispatcher\Dispatcher;

$dispatcher = new Dispatcher([
    new AuthMiddleware(),
    new LoggingMiddleware(),
    new FinalHandler(),   // implements RequestHandlerInterface
]);

$response = $dispatcher->dispatch($request);

Add middleware after construction with the fluent add() API:

$dispatcher = (new Dispatcher())
    ->add(new AuthMiddleware())
    ->add(new LoggingMiddleware())
    ->add(new FinalHandler());

$response = $dispatcher->dispatch($request);

Use dispatch() multiple times safely — the internal pointer is reset on every call:

$responseA = $dispatcher->dispatch($requestA);
$responseB = $dispatcher->dispatch($requestB); // works correctly

Invoke as a callable (e.g. in a routing layer):

$response = $dispatcher($request);

Linked-list MiddlewarePipe

use Horizom\Dispatcher\MiddlewarePipeFactory;

$factory = new MiddlewarePipeFactory();

$pipe = $factory->create([
    new AuthMiddleware(),
    new LoggingMiddleware(),
    new FinalHandler(),
]);

$response = $pipe->handle($request);

Merging pipelines

Sub-pipelines (instances of MiddlewarePipe) can be composed into a larger pipeline:

$authPipe = $factory->create([new AuthMiddleware(), new RateLimitMiddleware()]);

$pipe = $factory->create([
    $authPipe,               // merged in-place
    new LoggingMiddleware(),
    new FinalHandler(),
]);

Note: A sub-pipeline that contains an intermediate terminal RequestHandlerInterface (i.e. a handler that is not the EmptyRequestHandler sentinel) cannot be merged and will throw an InvalidArgumentException.

DispatcherFactory / MiddlewarePipeFactory

Both factories accept an optional MiddlewareResolverInterface argument:

use Horizom\Dispatcher\DispatcherFactory;
use Horizom\Dispatcher\MiddlewarePipeFactory;

$factory    = new DispatcherFactory($customResolver);
$dispatcher = $factory->create([AuthMiddleware::class, LoggingMiddleware::class]);

$pipeFactory = new MiddlewarePipeFactory($customResolver);
$pipe        = $pipeFactory->create([AuthMiddleware::class, FinalHandler::class]);

Resolving middleware from a PSR-11 container

Pass any PSR-11 ContainerInterface to MiddlewareResolver to enable string-based resolution:

use Horizom\Dispatcher\Dispatcher;
use Horizom\Dispatcher\MiddlewareResolver;

$resolver   = new MiddlewareResolver($container);
$dispatcher = new Dispatcher(
    [AuthMiddleware::class, LoggingMiddleware::class, FinalHandler::class],
    $resolver
);

$response = $dispatcher->dispatch($request);

The container must return an instance of MiddlewareInterface or RequestHandlerInterface, otherwise a TypeError is thrown with a descriptive message.

API Reference

Dispatcher

MiddlewarePipe

MiddlewareResolver

EmptyRequestHandler

Sentinel placed at the end of a MiddlewarePipe. Always throws RequestHandlerException.

Error Handling

Testing

composer install
vendor/bin/phpunit

53 tests, 76 assertions.

License

MIT © Roland Edi