horizom/dispatcher

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

Requirement	Version
PHP	^8.0
psr/http-message	^1.0 | ^2.0
psr/http-server-handler	^1.0
psr/http-server-middleware	^1.0
psr/container (optional)	^1.0 | ^2.0

---

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

Method	Description
__construct(array $middlewares = [], ?MiddlewareResolverInterface $resolver = null)	Build the dispatcher, optionally pre-loading middlewares.
add(MiddlewareInterface|RequestHandlerInterface|string $middleware): self	Append a middleware (fluent).
handle(ServerRequestInterface $request): ResponseInterface	Advance one step in the stack (PSR-15).
dispatch(ServerRequestInterface $request): ResponseInterface	Reset the pointer and run the full stack.
__invoke(ServerRequestInterface $request): ResponseInterface	Alias for dispatch().

MiddlewarePipe

Method	Description
__construct(MiddlewareInterface|RequestHandlerInterface $handler, RequestHandlerInterface $next)	Create a pipeline node.
handle(ServerRequestInterface $request): ResponseInterface	Execute this node and forward to $next if needed.
getHandler(): MiddlewareInterface|RequestHandlerInterface	Return the current handler.
getNext(): RequestHandlerInterface	Return the next node.
setNext(RequestHandlerInterface $next): void	Replace the next node.

MiddlewareResolver

Method	Description
__construct(?ContainerInterface $container = null)	Optionally inject a PSR-11 container.
resolve(MiddlewareInterface|RequestHandlerInterface|string $middleware): MiddlewareInterface|RequestHandlerInterface	Resolve a middleware instance (from container if string).

EmptyRequestHandler

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

---

Error Handling

Exception	Thrown when
RequestHandlerException	Dispatcher stack is exhausted / EmptyRequestHandler is reached.
TypeError	A string middleware cannot be resolved (no container, or container returns invalid type).
InvalidArgumentException	MiddlewarePipeFactory::create() receives an empty array, or a pipeline merge is impossible.

---

Testing

composer install
vendor/bin/phpunit

53 tests, 76 assertions.

---

License

MIT © Roland Edi