italystrap/pipeline

A lightweight middleware pipeline for PHP — chain handlers and middleware to process messages through a composable pipeline

dev-main 2026-04-07 14:28 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpbench/phpbench: ^1.6
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.0
• rector/rector: ^2.0
• symplify/easy-coding-standard: ^12.5

MIT

• Enea Overclokk

• middleware
• handler
• pipeline
• stack-handler

README

A lightweight, zero-dependency middleware pipeline for PHP.

Route any object through a composable pipeline of middleware before reaching a final handler — inspired by the HTTP middleware pattern (PSR-15).

Installation

composer require italystrap/pipeline

Quick Start

use ItalyStrap\Pipeline\Pipeline;
use ItalyStrap\Pipeline\CallbackHandler;
use ItalyStrap\Pipeline\HandlerInterface;
use ItalyStrap\Pipeline\MiddlewareInterface;

// 1. Define a message (any object mutable or immutable)
$message = new User(name: 'Alice', email: '[e-mail]');

// 2. Create a pipeline with a handler and middleware
$handler = new Pipeline(
    new CallbackHandler(static function (object $message): string {
        // final handler logic
        return 'User created: ' . $message->name;
    }),
    new LoggingMiddleware(),
    new ValidationMiddleware(),
);

// 3. Dispatch when ready
$result = $handler->handle($message);

The message flows through middleware in the order they were provided, then reaches the handler.

Documentation

• Overview — Architecture, pattern, and design rationale
• Interfaces — HandlerInterface and MiddlewareInterface
• Pipeline — The main pipeline dispatcher
• Helpers — CallbackHandler, DecorateHandler, NoHandlerProvided
• Pipeline vs DecorateHandler — When to use which
• Wrapping the Pipeline — Adapting the generic pipeline to typed contracts (e.g. CLI exit codes)

License

MIT — see LICENSE.