Middleware Pipeline

Purpose and Scope

This document describes the middleware pipeline system in Hypervel, focusing on how middleware is registered, organized, and applied to HTTP routes. The system supports middleware at three levels (global, group, and route-specific), provides middleware exclusion capabilities via without_middleware, and handles proper merging when routes are nested within groups.

For information about the overall HTTP request lifecycle, see Request Lifecycle and Processing. For details about route definition and dispatching, see Routing and Dispatching.

Middleware Registration Architecture

Hypervel's middleware system is built on top of Hyperf's MiddlewareManager but extends it with exclusion management and enhanced group merging capabilities. Middleware registration occurs during route definition and is stored separately from exclusion rules to enable proper filtering after group expansion.

Storage Components

Sources: src/router/src/RouteCollector.php75-79

The RouteCollector stores middleware and exclusions in separate managers during route registration:

• MiddlewareManager: Stores all middleware defined on routes and groups, including those that may later be excluded
• MiddlewareExclusionManager: Stores exclusion rules defined via without_middleware option

This two-phase approach ensures that group middleware is properly accumulated before exclusions are applied.

Sources: src/router/src/RouteCollector.php75-79 tests/Router/RouteCollectorTest.php128-163

Middleware Registration Flow

Sources: src/router/src/RouteCollector.php53-81 tests/Router/RouteCollectorTest.php151-156

Middleware Levels

Route-Level Middleware

Middleware can be attached directly to individual routes via the middleware option:

Sources: tests/Router/RouteCollectorTest.php80-82

Group-Level Middleware

Middleware defined in a route group is applied to all routes within that group. Group middleware is accumulated as routes are nested:

In this example, the route /api will have both api.auth (from group) and api.throttle (from route) middleware.

Sources: tests/Router/RouteCollectorTest.php74-108

Middleware Merging in Nested Groups

When groups are nested, middleware from parent groups is inherited and merged with child group middleware:

The mergeOptions() method uses array_merge_recursive() to combine middleware arrays, preserving duplicates:

Sources: src/router/src/RouteCollector.php104-113 tests/Router/RouteCollectorTest.php166-180

Global Middleware

Global middleware (middleware applied to all routes) is managed separately through Hyperf's middleware configuration system and is not handled by the RouteCollector. It is configured via the application's middleware configuration and applied during request processing.

Middleware Exclusion

The without_middleware option allows routes to exclude specific middleware that would otherwise be inherited from groups or applied globally.

Exclusion Syntax

Sources: tests/Router/RouteCollectorTest.php128-163

Exclusion Storage and Application

Exclusions are stored separately in MiddlewareExclusionManager and merged using the same recursive merge strategy as middleware:

Sources: tests/Router/RouteCollectorTest.php158-162

Exclusion Resolution Example

Given a route with group and route-level middleware and exclusions:

Level	Middleware	Exclusions
Group	['ApiGetMiddleware']	['FooGetMiddleware']
Route	['ApiSelfGetMiddleware']	['ApiGetMiddleware']
Stored (unfiltered)	['ApiGetMiddleware', 'ApiSelfGetMiddleware']	['FooGetMiddleware', 'ApiGetMiddleware']
Resolved (filtered)	['ApiSelfGetMiddleware']	N/A

In this example, both ApiGetMiddleware and FooGetMiddleware are removed from the final middleware stack because they appear in the exclusion list.

Sources: tests/Router/RouteCollectorTest.php138-162

RouteCollector Integration

The RouteCollector class is responsible for registering middleware during route definition. Key implementation details:

addRoute Method

The src/router/src/RouteCollector.php53-81 method performs the following steps:

1. Parse route and options: Extracts handler and options from parameters
2. Merge options: Combines group options with route options using mergeOptions()
3. Register route: Adds route to the route data generator
4. Store middleware: Calls MiddlewareManager::addMiddlewares() with unwrapped middleware array
5. Store exclusions: Calls MiddlewareExclusionManager::addExcluded() with unwrapped exclusion array

Sources: src/router/src/RouteCollector.php53-81

Middleware Option Merging

The mergeOptions() method handles special treatment for the as option (route naming) while merging all other options recursively:

Sources: src/router/src/RouteCollector.php104-113

Middleware Storage Schema

MiddlewareManager Structure

MiddlewareManager::$container = [
 'http' => [ // Server name
 '/' => [ // Route pattern
 'GET' => ['Middleware1', 'Middleware2'],
 'POST' => ['Middleware3']
 ],
 '/api/users' => [
 'GET' => ['Auth', 'Throttle']
 ]
 ],
 'test' => [ // Another server
 // ...
 ]
]

Sources: tests/Router/RouteCollectorTest.php103-108

MiddlewareExclusionManager Structure

MiddlewareExclusionManager::$container = [
 'http' => [ // Server name
 '/' => [ // Route pattern
 'GET' => ['PostMiddleware'], // Excluded middleware
 ],
 '/api' => [
 'GET' => ['FooGetMiddleware', 'ApiGetMiddleware']
 ]
 ]
]

Sources: tests/Router/RouteCollectorTest.php158-162

Route Initialization and Middleware Reset

When the DispatcherFactory initializes routes, it clears the MiddlewareManager container to ensure a clean state:

This reset occurs before route files are loaded, ensuring that middleware registration starts fresh each time routes are initialized. The exclusion manager is also cleared at the same time.

Sources: src/router/src/DispatcherFactory.php22-37 tests/Router/RouteCollectorTest.php21-27

Optional Routes and Middleware

Routes with optional parameters (e.g., /user/[{id:\d+}]) store middleware under their exact pattern as defined. The middleware is associated with the route pattern as registered, not with each variation the optional parameters might create:

Sources: tests/Router/RouteCollectorTest.php182-198

Multi-Server Support

The middleware system supports multiple servers (e.g., http, ws, test) through the RouteCollector constructor's $server parameter. Each server maintains its own isolated middleware and exclusion storage:

Sources: tests/Router/RouteCollectorTest.php110-126

Summary

The middleware pipeline in Hypervel provides:

• Three-level middleware: Global (via config), group-level, and route-level
• Recursive merging: Middleware accumulates through nested groups via array_merge_recursive()
• Selective exclusion: The without_middleware option removes specific middleware from inherited stacks
• Deferred filtering: Middleware is stored unfiltered during registration; exclusions are applied at resolution time
• Multi-server isolation: Each server name maintains separate middleware storage
• Integration with Hyperf: Uses Hyperf's MiddlewareManager while extending with custom exclusion management

This architecture enables flexible middleware composition while maintaining clean separation between registration and resolution phases.

Sources: src/router/src/RouteCollector.php53-81 src/router/src/DispatcherFactory.php22-37 tests/Router/RouteCollectorTest.php74-163