> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/core-concepts/middleware.md). # Middleware Middleware is the part of the Quantum PHP Framework that runs between route matching and the final controller action. It gives you a way to inspect, block, validate, or redirect a request before the main handler continues. ## Core idea A simple way to think about middleware is: * the router finds the matching route * Quantum checks the route's middleware list * each middleware gets a chance to run * if all middlewares allow the request, the controller action continues * if one middleware stops the request, the action does not run So middleware acts like a request gatekeeper. ## Why middleware belongs in core concepts In Quantum, middleware is not a side feature. It is wired directly into the request flow: * routes attach middleware names * matched routes carry those middleware definitions * `MiddlewareManager` loads middleware classes from the current module * each middleware runs through the `apply()` contract That makes middleware part of the core request lifecycle. ## How middleware is attached Middleware is usually attached in route files. A single route can define middleware like this: ```php $route->post('signup', 'AuthController', 'signup')->middlewares(['Signup']); ``` A route group can also share middleware: ```php $route->group('auth', function ($route) { $route->get('my-posts', 'PostManagementController', 'myPosts'); $route->get('signout', 'AuthController', 'signout'); })->middlewares(['Auth']); ``` This is one reason middleware feels central in Quantum. You see it directly inside the routing layer. ## The middleware contract At the framework level, middleware classes extend `Quantum\Middleware\Middleware` and implement: ```php apply(Request $request, Closure $next): Response ``` That means every middleware receives: * the current request * a `$next` callback for continuing the pipeline **Note**: Middleware instances are constructed as `new $middlewareClass($request)` by the `MiddlewareManager` before the `apply()` method is executed. If the middleware calls `$next($request)`, processing continues. If it does not, the request stops there. ## How Quantum resolves middleware classes From the upstream `MiddlewareManager`, Quantum resolves middleware classes by module. In practice, it expects names like: ``` \\Middlewares\ ``` That means route middleware names such as `Auth` or `Guest` are usually resolved to classes inside the current module's `Middlewares` directory. ## Where middleware lives From the module templates, middleware classes typically live under: ``` modules//src/Middlewares/ ``` Examples from the upstream templates include: * `Auth` * `Guest` * `Editor` * `Signup` * `Reset` * `Verify` * `PostOwner` * `BasicAuth` ## Common middleware jobs The upstream templates show several common middleware responsibilities. ### Authentication Example: * `Auth` This checks whether the user is authenticated before allowing access. ### Guest-only access Example: * `Guest` This prevents authenticated users from visiting routes meant only for guests, such as sign-in pages. ### Authorization and ownership Examples: * `Editor` * `PostOwner` * `CommentOwner` These restrict actions based on role or ownership. ### Request validation Some middleware classes validate incoming data before allowing the request to continue. The `Editor` middleware template is a good example. It validates request fields and uploaded image constraints before continuing. ### HTTP basic auth The Toolkit template includes `BasicAuth`, which protects routes using HTTP basic authentication. ## Web and API middleware behave differently The upstream templates show an important pattern. ### Web middleware Often redirects the user when access fails. For example: * redirect unauthenticated users to sign-in * redirect authenticated users away from guest-only pages * flash validation errors and redirect back ### API middleware Usually returns JSON errors instead. For example: * unauthorized requests return a JSON error response * validation failures return structured error payloads This is an important lesson: middleware behavior should fit the kind of application surface you are building. ## Complete middleware class example A middleware doc should not stop at the method signature. It should also show a full class example grounded in the real upstream templates. Here is the actual structure used by the upstream `Auth` middleware template: ```php check()) { redirect(base_url(true) . '/' . current_lang() . '/signin'); } return $next($request); } } ``` What this real template example shows: * middleware classes live in the module `Middlewares` namespace * they extend `Quantum\Middleware\Middleware` * they receive `Request` and `Closure $next` * they can stop the request with a redirect * they continue the pipeline with `$next($request)` This is much closer to what you actually generate in Quantum than a generic framework-style example. If you want more advanced middleware examples, the upstream templates also include `Editor`, `PostOwner`, and `CommentOwner`, which build on validation and ownership checks through a shared `BaseMiddleware`. ## Base middleware classes The demo templates include `BaseMiddleware` classes for both web and API modules. These base classes help share things like: * validator setup * request validation logic * common error response behavior That is useful because real applications often have many middlewares, and repeated validation or response code becomes messy fast. ## Middleware order Quantum's `MiddlewareManager` processes the middleware queue in order. So if a route has several middlewares attached, they run one after another. That matters because the first middleware that blocks or redirects can prevent the rest of the pipeline from running. ## What happens when middleware fails A middleware can stop the request in different ways, depending on how it is written. From the upstream templates, common outcomes include: * redirecting the user * returning a JSON error * sending a 401 response * stopping further execution So middleware is not only about validation. It is also a control point for access and response flow. ## Practical view A useful way to think about middleware in Quantum is: * routes decide where the request wants to go * middleware decides whether the request is allowed to continue * controllers handle the request only after middleware passes ## What to read next After middleware, good next steps are: * [Request Handling](/docs/core-concepts/request.md) * [Modules](/docs/core-concepts/modules.md) * [First App](/docs/getting-started/first-app.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://quantumphp.gitbook.io/docs/core-concepts/middleware.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.