Slim Middleware

When to use

• The user wants to add PSR-15 middleware to a Slim app or a specific route or group.
• The user needs Slim middleware that runs logic before and after the handler around $handler->handle().
• The user is reasoning about the execution order of stacked Slim middleware and the onion model.

When NOT to use

• Do not run long-running or background work inside middleware on the request path.
• Do not build middleware for logic that concerns only a single route and is not cross-cutting.

Core guidance

• Implement MiddlewareInterface with process() — Write middleware as a class implementing PSR-15 MiddlewareInterface::process(Request $request, RequestHandler $handler) and call $handler->handle($request) to continue the chain.

Quick recipe

1. Create a class implementing MiddlewareInterface with a process() method. (verify: The class satisfies the PSR-15 interface.)
2. Do request work before $handler->handle($request), then decorate the returned response after it before returning. (verify: Both the request and response phases run as expected.)
3. Add the middleware with $app->add(), group ->add(), or $route->add(), remembering LIFO order. (verify: The middleware runs at the intended position in the onion.)

Best practices

• Put request inspection and short-circuits before $handler->handle(), and response decoration (headers, timing) after it on the returned response
• Remember Slim runs middleware LIFO: the last one added wraps the others, so add the outermost concern (e.g
• Attach middleware at the narrowest useful scope: $app->add() for global, group ->add() for a section, and $route->add() for one route
• To reject a request (e.g

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Forgetting to call $handler->handle() — Middleware that never calls $handler->handle() silently stops the chain, so the route handler never runs. Fix: Call $handler->handle($request) and return its response unless you intend to short-circuit.
2. Expecting request changes to propagate without passing them on — Attributes added with $request->withAttribute(...) do not reach the handler unless the new request is passed to $handler->handle(). Fix: Capture the new request and delegate with it: $request = $request->withAttribute(...); return $handler->handle($request).
3. Middleware runs in the opposite order expected — Middleware appears to run in reverse because Slim executes the stack LIFO. Fix: Add middleware in reverse of the desired run order, or reason explicitly with the onion model.

Version notes

• Slim 4 standardized on PSR-15 middleware (PHP >=7.4) — Slim 4 uses the PSR-15 MiddlewareInterface signature; the Slim 3 double-pass function ($req, $res, $next) signature is no longer the primary contract.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/slim/middleware.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: slim/routing