README

This library provides a middleware execution engine and a routing component for building HTTP services.
It is designed to be simple, explicit, and framework-agnostic — you can drop it into any project and wire up your own request/response handling.

Middleware Engine

At the core is the StackEngine contract, implemented by OrderedStackEngine.

Middleware are small units of code that take a Request, do some work, and then either:
- Call the next middleware in the stack, or
- Short-circuit the pipeline and return a Response.
Middleware can be registered in a specific order, and can be filtered by HTTP verb flags.
The engine supports optional exception catching, so uncaught exceptions can be converted into 500 Internal Server Error responses.

This gives you a pipeline model where cross-cutting concerns like logging, auth, or body parsing can be layered transparently.

Router

The MiddlewareRouter component acts as both:

A Router, capable of dispatching requests to controllers based on HTTP verb and URI pattern.
A Middleware, so it can slot into the stack like any other component.

Features

Path patterns:
- * wildcard segments.
- Placeholders: {id}, {id:int}, {slug:alpha}.
- Value sets: {status:[open|closed|pending]}.
- Optional segments prefixed with ?.
Named routes:
Define routes with a name and later generate the corresponding path with dynamic values (getNamedPath()).
Binding of route parameters:
When a path matches, placeholders are automatically injected into the request attributes using the key format bound-{name}.
Example: a route /users/{id:int} will yield $request->getAttribute("bound-id").
Controller flexibility:
Controllers can be:
- A callable (closure or function),
- A class implementing the Controller interface, or
- A class name string (which will be instantiated if it implements Controller).

Composition

Because the router itself is a middleware, you can:

Use OrderedStackEngine to build a layered stack:

$engine = new OrderedStackEngine();
$engine->addMiddleware(10, Verb::ANY, SomeAuthMiddleware::class);
$engine->addMiddleware(50, Verb::GET|Verb::POST, new MiddlewareRouter());
$response = $engine->process($request);

Or just use the router directly if you don’t need a full middleware stack:

$router = new MiddlewareRouter();
$router->addRoute("/hello", Verb::GET, fn($req) => new Response("Hello World"));
$response = $router->process($request);

Philosophy

This library is intentionally minimal:

No global state — everything is explicit and injectable.
Small contracts (Middleware, StackEngine, Router, Controller) define clear extension points.
Predictable behavior — request goes in, response comes out, with optional error handling.

The idea is to give you a solid foundation for building your own micro-frameworks, HTTP services, or experimental backends, without forcing a specific architecture or heavy dependency tree.

gabbro-php / middleware

Maintainers

Details