Middleware Adaptation System

Purpose and Scope

The Middleware Adaptation System provides two adapter classes that enable interoperability between PSR-15 standard middleware and Hypervel's closure-based middleware system:

• Psr15AdapterMiddleware - Wraps PSR-15 MiddlewareInterface instances to work with Hypervel's handle(ServerRequestInterface, Closure) signature
• AdaptedRequestHandler - Wraps closure-based $next handlers to implement PSR-15's RequestHandlerInterface

These adapters allow PSR-15 middleware, CoreMiddlewareInterface implementations, and closure-based middleware to coexist in the same pipeline. For middleware parsing from string definitions, see page 2.4. For the overall pipeline execution flow, see page 2.2.

System Overview

The adaptation system operates within the Pipeline::carry() method, which processes each middleware item in the pipeline stack. When PSR-15 middleware is encountered, it is wrapped in Psr15AdapterMiddleware, which internally creates AdaptedRequestHandler instances to bridge the closure-based $next handler to PSR-15's RequestHandlerInterface.

Adapter Component Relationships

Sources: src/Pipeline.php21-86 src/Psr15AdapterMiddleware.php12-28 src/AdaptedRequestHandler.php13-31

Key Components

AdaptedRequestHandler

AdaptedRequestHandler implements PSR-15's RequestHandlerInterface by wrapping a closure-based $next handler. This allows PSR-15 middleware to call $handler->handle($request) while the underlying system uses $next($request).

Class Structure

Constructor Parameters

Parameter	Type	Purpose
$next	Closure	The next middleware handler in the pipeline
$overrideResponse	bool	Whether to store response in Context::set(ResponseInterface::class)

Execution Flow

1. PSR-15 middleware calls $handler->handle($request)
2. AdaptedRequestHandler::handle() invokes ($this->next)($request) at src/AdaptedRequestHandler.php23
3. If $overrideResponse is true, stores result in Context::set(ResponseInterface::class, $response) at src/AdaptedRequestHandler.php26
4. Returns the response

Sources: src/AdaptedRequestHandler.php13-31

Psr15AdapterMiddleware

Psr15AdapterMiddleware adapts PSR-15 MiddlewareInterface implementations to work with Hypervel's closure-based pipeline signature. It converts the pipeline's handle(ServerRequestInterface, Closure, ...$arguments) signature to PSR-15's process(ServerRequestInterface, RequestHandlerInterface) signature.

Class Structure

Constructor Parameters

Parameter	Type	Purpose
$middleware	MiddlewareInterface	The PSR-15 middleware to adapt
$overrideResponse	bool	Whether to store response in Context (passed to AdaptedRequestHandler)

Method Signature Transformation

The adapter transforms method signatures as follows:

Pipeline signature: handle(ServerRequestInterface $request, Closure $next, ...$arguments)
 ↓ (adaptation)
PSR-15 signature: process(ServerRequestInterface $request, RequestHandlerInterface $handler)

The Closure $next is wrapped in an AdaptedRequestHandler instance at src/Psr15AdapterMiddleware.php24 then passed to $middleware->process().

Sources: src/Psr15AdapterMiddleware.php12-28

Middleware Adaptation Flow

When the Pipeline encounters PSR-15 middleware, the following adaptation sequence occurs:

PSR-15 Middleware Execution Sequence

Sources: src/Psr15AdapterMiddleware.php20-27 src/AdaptedRequestHandler.php21-30

Pipeline Integration and Caching

The Pipeline class integrates the adaptation system through two key methods: getPipeInstance() for regular middleware and getAdaptedCoreMiddleware() for Hyperf's CoreMiddlewareInterface.

Middleware Resolution and Caching

Caching Strategy

The Pipeline maintains two cache arrays to avoid recreating adapter instances:

Cache Array	Key	Value	Purpose
$adaptedMiddleware	Middleware class name (string)	Psr15AdapterMiddleware instance	Caches adapted PSR-15 middleware resolved from container
$coreMiddleware	Core middleware class name (string)	Psr15AdapterMiddleware instance	Caches adapted CoreMiddlewareInterface instances with overrideResponse=true

Implementation at src/Pipeline.php72-86 and src/Pipeline.php62-70

CoreMiddlewareInterface Adaptation

CoreMiddlewareInterface instances are always adapted with overrideResponse=true, ensuring responses are stored in Hyperf's Context system via Context::set(ResponseInterface::class, $response).

Sources: src/Pipeline.php14-86

Context Integration

The overrideResponse flag controls whether responses are stored in Hyperf's Context system. This flag is set at adapter construction and passed through to AdaptedRequestHandler.

Response Storage Flow

Usage Patterns

Middleware Type	overrideResponse	Rationale
Regular PSR-15 middleware	false (default)	Response flows naturally through pipeline
CoreMiddlewareInterface	true (forced)	Ensures response is accessible in Context for Hyperf integration

The Context storage occurs at src/AdaptedRequestHandler.php25-27 making the response accessible via Context::get(ResponseInterface::class) throughout the application.

Sources: src/AdaptedRequestHandler.php21-30 src/Pipeline.php69

Interoperability Benefits

The adaptation system enables multiple middleware standards to coexist in a single pipeline:

Supported Middleware Types

Interoperability Matrix

Middleware Type	Adaptation Required	Adapter Class	Caching Location
Closure	No	N/A	Not cached
MiddlewareInterface (PSR-15)	Yes	Psr15AdapterMiddleware	Pipeline::$adaptedMiddleware
CoreMiddlewareInterface	Yes	Psr15AdapterMiddleware (overrideResponse=true)	Pipeline::$coreMiddleware
String (resolves to PSR-15)	Yes	Psr15AdapterMiddleware	Pipeline::$adaptedMiddleware
String (resolves to Closure)	No	N/A	Not cached

Sources: src/Pipeline.php21-86 src/Psr15AdapterMiddleware.php12-28 src/AdaptedRequestHandler.php13-31

Summary

The Middleware Adaptation System provides a flexible foundation for the Hypervel Dispatcher by:

1. Adapting different middleware formats to work in a unified pipeline
2. Supporting PSR-15 compliant middleware
3. Providing context integration for response management
4. Creating a bridge between middleware definitions and executable components

This system is essential for the dispatcher's ability to handle heterogeneous middleware configurations while maintaining a consistent execution flow.