Middleware Architecture 🔗

<?php
// A request travels INTO the handler, then a response travels back OUT.
// One middleware "wraps" the controller: it runs code before AND after.

// The controller is the innermost layer — it produces the response.
$controller = function (array $request): array {
    return ["status" => 200, "body" => "Hello, {$request['user']}!"];
};

// A logging middleware wraps it. $next is "the rest of the pipeline".
$logging = function (array $request, callable $next): array {
    echo "[in ] {$request['method']} {$request['path']}\n"; // BEFORE: on the way in
    $response = $next($request);                              // hand off to $controller
    echo "[out] status {$response['status']}\n";            // AFTER: on the way out
    return $response;                                         // pass the response back
};

// Run it: the middleware calls $next, which is the controller.
$response = $logging(
    ["method" => "GET", "path" => "/home", "user" => "Sam"],
    $controller
);
echo "Body: {$response['body']}\n";

[in ] GET /home
[out] status 200
Body: Hello, Sam!

<?php
// Real frameworks use PSR-15: a middleware has a single handle($request, $next).
// Here we model $request/$response as arrays to keep the focus on the PIPELINE.

interface Middleware
{
    // $next is a callable: "process the rest of the stack and give me a response".
    public function handle(array $request, callable $next): array;
}

final class Pipeline
{
    /** @var Middleware[] */
    private array $stack = [];

    public function pipe(Middleware $mw): self
    {
        $this->stack[] = $mw;
        return $this;          // return $this so calls can be chained
    }

    public function process(array $request, callable $controller): array
    {
        // Compose inside-out: wrap the controller with the LAST middleware first,
        // so the FIRST one you piped ends up on the OUTSIDE and runs first.
        $next = $controller;
        foreach (array_reverse($this->stack) as $mw) {
            $current = $next;  // capture the inner layer for this closure
            $next = fn (array $req) => $mw->handle($req, $current);
        }
        return $next($request);
    }
}

final class LoggingMiddleware implements Middleware
{
    public function handle(array $request, callable $next): array
    {
        echo "[LOG] {$request['method']} {$request['path']}\n";
        $response = $next($request);                       // continue the pipeline
        echo "[LOG] responded {$response['status']}\n";
        return $response;
    }
}

final class AuthMiddleware implements Middleware
{
    public function handle(array $request, callable $next): array
    {
        if (empty($request["headers"]["Authorization"])) {
            echo "[AUTH] rejected — no token\n";
            return ["status" => 401, "body" => "Unauthorized"]; // short-circuit: no $next
        }
        $request["user"] = "Alice";                        // pretend we decoded the token
        echo "[AUTH] ok — {$request['user']}\n";
        return $next($request);                            // authorised: continue
    }
}

// Pipe order = run order. Logging is outermost, Auth is inside it.
$pipeline = (new Pipeline())
    ->pipe(new LoggingMiddleware())
    ->pipe(new AuthMiddleware());

$controller = fn (array $req) => ["status" => 200, "body" => "Users for {$req['user']}"];

echo "--- request WITH token ---\n";
$ok = $pipeline->process(
    ["method" => "GET", "path" => "/api/users", "headers" => ["Authorization" => "Bearer x"]],
    $controller
);
echo "final: {$ok['status']} {$ok['body']}\n\n";

echo "--- request WITHOUT token ---\n";
$blocked = $pipeline->process(
    ["method" => "GET", "path" => "/api/users", "headers" => []],
    $controller
);
echo "final: {$blocked['status']} {$blocked['body']}\n";

--- request WITH token ---
[LOG] GET /api/users
[AUTH] ok — Alice
[LOG] responded 200
final: 200 Users for Alice

--- request WITHOUT token ---
[LOG] GET /api/users
[AUTH] rejected — no token
[LOG] responded 401
final: 401 Unauthorized

<?php
// CORS middleware adds cross-origin headers to the RESPONSE — work done AFTER $next.
// It also answers a browser "preflight" (an OPTIONS request) without hitting the app.

final class CorsMiddleware
{
    public function __construct(private string $allowOrigin) {}

    public function handle(array $request, callable $next): array
    {
        // Browsers send OPTIONS first to ask "am I allowed?". Reply immediately.
        if ($request["method"] === "OPTIONS") {
            return ["status" => 204, "headers" => $this->corsHeaders(), "body" => ""];
        }

        $response = $next($request);                       // run the real handler
        // Merge CORS headers onto whatever the handler returned.
        $response["headers"] = ($response["headers"] ?? []) + $this->corsHeaders();
        return $response;
    }

    private function corsHeaders(): array
    {
        return [
            "Access-Control-Allow-Origin"  => $this->allowOrigin,
            "Access-Control-Allow-Methods" => "GET, POST, OPTIONS",
        ];
    }
}

$cors = new CorsMiddleware("https://app.example.com");
$handler = fn (array $req) => ["status" => 200, "body" => "data"];

$res = $cors->handle(["method" => "GET"], $handler);
echo "GET  -> {$res['status']} origin={$res['headers']['Access-Control-Allow-Origin']}\n";

$pre = $cors->handle(["method" => "OPTIONS"], $handler);
echo "OPTIONS preflight -> {$pre['status']} (handler never ran)\n";

GET  -> 200 origin=https://app.example.com
OPTIONS preflight -> 204 (handler never ran)

<?php
// 🎯 YOUR TURN — finish this timing middleware, then run it.
// A timer measures how long the rest of the pipeline takes. To do that it must
// record the time, CALL THE NEXT LAYER, then measure again.

$timing = function (array $request, callable $next): array {
    $start = microtime(true);

    // 1) Run the rest of the pipeline and capture its response.
    $response = ___;          // 👉 call the next layer:  $next($request)

    $ms = round((microtime(true) - $start) * 1000, 1);
    echo "[time] {$request['path']} took {$ms}ms\n";

    // 2) Always hand the response back to the layer outside you.
    return ___;               // 👉 return the response you captured above
};

$controller = fn (array $req) => ["status" => 200, "body" => "ok"];
$result = $timing(["path" => "/report"], $controller);
echo "status: {$result['status']}\n";

// ✅ Expected output (the ms number will vary):
//    [time] /report took 0ms
//    status: 200

[time] /report took 0ms
status: 200

<?php
// 🎯 YOUR TURN — fix the ORDER so errors are caught.
// The controller throws. Only the ErrorHandler can turn that into a 500 response,
// so it MUST sit on the OUTSIDE of the layer that throws.

final class ErrorHandler
{
    public function handle(array $request, callable $next): array
    {
        try {
            return $next($request);
        } catch (\Throwable $e) {
            echo "[error] caught: {$e->getMessage()}\n";
            return ["status" => 500, "body" => "Server Error"];
        }
    }
}

$throws = function (array $req): array {
    throw new \RuntimeException("database is down");
};

$error = new ErrorHandler();

// 👉 Wrap the throwing handler with the error handler.
//    Fill the blank so $error->handle runs FIRST and $throws is its $next.
$response = ___;   // 👉 e.g.  $error->handle(["path" => "/users"], $throws)

echo "final: {$response['status']} {$response['body']}\n";

// ✅ Expected output:
//    [error] caught: database is down
//    final: 500 Server Error

[error] caught: database is down
final: 500 Server Error