Middleware: The Wrap

What middleware is

A middleware is a function that gets the request before your handler, and gets the response after. It can short-circuit the request (returning 401 before authentication even reaches your route), add a header to every response (compression, CORS, ETag), measure timing, log, anything that should apply to many routes rather than one.

ZealPHP uses the PSR-15 middleware shape. A middleware implements:

public function process(
    ServerRequestInterface $request,
    RequestHandlerInterface $handler
): ResponseInterface;

You either return a response yourself (short-circuit) or call $handler->handle($request) to delegate to the next middleware in the chain. Same shape Slim, Symfony, Laravel (via adapters), and most modern PHP frameworks use.

The six built-ins

ZealPHP ships these out of the box. Most apps register the first four.

Register them in app.php before $app->run():

$app->addMiddleware(new CorsMiddleware());
$app->addMiddleware(new ETagMiddleware());
$app->addMiddleware(new SessionStartMiddleware());

Order is reversed at execution time

You register A, B, C. The stack ZealPHP builds is C wraps B wraps A wraps ResponseMiddleware. At request time, C runs first. The last middleware you add is the outermost wrapper — same convention as Slim, Express, Laravel.

This means: register the inner-most concerns first, the outer-most last. Session handling is closest to the route handler — register early. CORS handles every response including 404s — register last.

Writing your own

Here’s a complete rate-limit-header middleware in 10 lines:

use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

class RateLimitHeader implements MiddlewareInterface {
    public function __construct(private int $limit = 60) {}

    public function process($request, RequestHandlerInterface $handler) {
        $response = $handler->handle($request);
        return $response
            ->withHeader('X-RateLimit-Limit', (string)$this->limit)
            ->withHeader('X-RateLimit-Remaining', (string)($this->limit - 1));
    }
}

// in app.php
$app->addMiddleware(new RateLimitHeader(100));

The pattern: call $handler->handle(), modify the returned response, return it. For short-circuit behavior (e.g., auth that returns 401 before the route runs), build a response yourself with new \OpenSwoole\Core\Psr\Response(...) and return it without calling $handler->handle() at all.

When NOT to write middleware

If the logic applies to one route, it goes in the handler. If it’s really tangled with request-specific data, it goes in the handler. If you find yourself reaching for middleware to validate a single form, you’ve over-engineered — just validate in the handler and return 422.

Middleware shines for cross-cutting concerns: things every route benefits from (CORS, logging, sessions) or things you can turn on/off as a feature flag (compression, rate-limiting, auth-required gates).

Try it live

The demo app registers CORS + ETag + Session-start + Range. See the headers in action:

• CORS: Access-Control-* headers
• ETag: 304 Not Modified on repeat
• Gzip compression: Content-Encoding: gzip