Pipeline Implementation

Purpose and Scope

This document details the Pipeline class implementation, which extends Hyperf's base pipeline to process middleware sequences in the hypervel/dispatcher package. The Pipeline is responsible for resolving middleware from various sources (closures, PSR-15 middleware, CoreMiddleware, and string definitions), caching adapted instances for performance, and executing them in sequence through the carry() method.

For information about how the HttpRequestHandler orchestrates the Pipeline, see HTTP Request Handler. For detailed information about middleware adaptation mechanisms, see Middleware Adaptation System. For middleware string parsing details, see Middleware Parsing.

Class Overview

The Pipeline class is defined in src/Pipeline.php12 and extends Hyperf\Pipeline\Pipeline. It serves as the execution engine that processes middleware chains, handling multiple middleware formats and maintaining performance optimizations through caching.

Core Properties

Property	Type	Purpose
$adaptedMiddleware	array	Caches PSR-15 middleware wrapped in Psr15AdapterMiddleware instances
$coreMiddleware	array	Caches CoreMiddleware instances wrapped in Psr15AdapterMiddleware instances
$container	ContainerInterface	Inherited from BasePipeline, used to resolve middleware instances
$method	string	Inherited from BasePipeline, specifies the method name to call on middleware

Sources: src/Pipeline.php12-16

Middleware Processing Flow

The Pipeline processes middleware through a nested closure pattern inherited from Hyperf's BasePipeline. The carry() method is the core of this execution flow.

Diagram: Middleware Type Resolution and Execution Flow

Sources: src/Pipeline.php21-60

The carry() Method

The carry() method returns a closure that creates the middleware "onion" layer. Each invocation wraps the next layer of middleware, creating a nested execution chain.

Diagram: carry() Method Execution Sequence

Sources: src/Pipeline.php21-60

Middleware Type Handling

The carry() method handles four distinct middleware types:

1. Callable Middleware (Closures)

When middleware is a callable (closure or invokable object), it is executed directly:

src/Pipeline.php25-29

The callable receives two parameters:

• $passable - The request object flowing through the pipeline
• $stack - The next handler in the chain

2. String and ParsedMiddleware

String middleware definitions are parsed to extract the middleware name and parameters:

src/Pipeline.php31-43

The process involves:

1. Extract $name and $parameters from the string (e.g., 'auth:api,admin' → name: 'auth', parameters: ['api', 'admin'])
2. Resolve the middleware instance via getPipeInstance($name)
3. Merge parameters: [$passable, $stack, ...parameters]

3. CoreMiddlewareInterface

CoreMiddleware instances require special adaptation to work with PSR-15:

src/Pipeline.php46-48

The getAdaptedCoreMiddleware() method wraps them in Psr15AdapterMiddleware with the $isCoreMiddleware flag set to true.

4. Other Objects

Object instances that don't fit the above categories are processed with basic parameters:

src/Pipeline.php49-53

Sources: src/Pipeline.php21-60

Middleware Resolution and Caching

The Pipeline implements two caching mechanisms to optimize performance by avoiding redundant object creation and adaptation.

getPipeInstance() Method

This method resolves middleware from the container and applies caching for PSR-15 middleware:

Diagram: Middleware Resolution and PSR-15 Adaptation Caching

src/Pipeline.php72-86

The caching strategy ensures that:

• PSR-15 middleware is wrapped in Psr15AdapterMiddleware only once per class
• Non-PSR-15 middleware is returned directly without adaptation
• Subsequent requests reuse the cached adapted instance

Sources: src/Pipeline.php72-86

getAdaptedCoreMiddleware() Method

CoreMiddleware instances receive similar caching treatment:

src/Pipeline.php62-70

The process:

1. Extract the class name using get_class($coreMiddleware)
2. Check the $coreMiddleware cache array
3. If cached, return the existing Psr15AdapterMiddleware instance
4. If not cached, create a new Psr15AdapterMiddleware($coreMiddleware, true) and cache it

The second parameter true indicates this is a CoreMiddleware, which affects how the adapter processes it.

Sources: src/Pipeline.php62-70

Middleware Type Support Matrix

The Pipeline supports the following middleware types:

Middleware Type	Format	Resolution Method	Adaptation Required	Cached
Closure	Closure	Direct execution	No	No
String Definition	'middleware:param1,param2'	Container + parse	Conditional	Yes (if PSR-15)
ParsedMiddleware	ParsedMiddleware object	Container	Conditional	Yes (if PSR-15)
PSR-15 Middleware	MiddlewareInterface	Container	Yes → Psr15AdapterMiddleware	Yes
CoreMiddleware	CoreMiddlewareInterface	Direct	Yes → Psr15AdapterMiddleware	Yes
Other Objects	Any object	Container	No	No

Sources: src/Pipeline.php21-86

Integration with ParsedMiddleware

The Pipeline accepts both raw string middleware definitions and pre-parsed ParsedMiddleware objects:

Diagram: ParsedMiddleware Integration Flow

src/Pipeline.php31-43

When a ParsedMiddleware object is encountered:

1. Extract $name via $pipe->getName()
2. Extract $parameters via $pipe->getParameters()
3. Resolve the middleware instance
4. Merge parameters for execution

This allows pre-processing of middleware signatures before they reach the Pipeline, enabling optimization and validation at an earlier stage.

Sources: src/Pipeline.php31-37 src/ParsedMiddleware.php1-43

Execution and Result Handling

After middleware resolution and parameter preparation, the Pipeline executes the middleware:

src/Pipeline.php55-57

The execution logic:

1. Check if the middleware object has the configured method (typically 'process')
2. If method exists, call $pipe->{$this->method}(...$parameters)
3. If method doesn't exist, invoke the object directly as callable: $pipe(...$parameters)
4. Pass the result through handleCarry() for post-processing (inherited from BasePipeline)

Sources: src/Pipeline.php55-57

Performance Considerations

The Pipeline implementation includes several performance optimizations:

Cache Arrays

Two cache arrays prevent redundant object creation:

• $adaptedMiddleware src/Pipeline.php14: Stores PSR-15 middleware wrapped in adapters, keyed by middleware class name
• $coreMiddleware src/Pipeline.php16: Stores CoreMiddleware wrapped in adapters, keyed by CoreMiddleware class name

Direct Execution Path

Closure middleware bypasses all resolution and adaptation logic src/Pipeline.php25-29 providing the fastest execution path for performance-critical middleware.

Lazy Adaptation

Middleware is only adapted when necessary:

• Non-PSR-15 middleware from the container is never wrapped
• PSR-15 middleware is only wrapped once and then cached
• Closures are never wrapped

Sources: src/Pipeline.php14-16 src/Pipeline.php72-86 src/Pipeline.php62-70

Class Hierarchy

Diagram: Pipeline Class Relationships

Sources: src/Pipeline.php12