HTTP Request Handler

Purpose and Scope

This document provides a detailed explanation of the HttpRequestHandler class, which serves as the primary entry point for HTTP request processing in the hypervel/dispatcher package. The handler implements the PSR-15 RequestHandlerInterface and orchestrates the execution of middleware chains through the Pipeline component.

For information about how the Pipeline processes middleware sequences, see Pipeline Implementation. For details on how middleware is adapted between different standards, see Middleware Adaptation System. For package-level configuration and registration, see Configuration.

Sources: composer.json1-47 class_map/HttpRequestHandler.php1-34

---

Class Location and Namespace

The HttpRequestHandler class is located at class_map/HttpRequestHandler.php1-34 and resides in the Hyperf\Dispatcher namespace rather than the Hypervel\Dispatcher namespace. This namespace choice is intentional and strategic—it allows the class to replace Hyperf's default HttpRequestHandler implementation through class mapping.

Diagram: Class Mapping Strategy

The class mapping is registered through the ConfigProvider, which tells Hyperf's dependency injection container to use this custom implementation whenever Hyperf\Dispatcher\HttpRequestHandler is requested.

Sources: class_map/HttpRequestHandler.php5-14 composer.json34-37

---

Class Structure and Dependencies

Class Declaration

The HttpRequestHandler implements Psr\Http\Server\RequestHandlerInterface, ensuring PSR-15 compliance for interoperability with standard HTTP middleware:

class_map/HttpRequestHandler.php14

Constructor Parameters

The constructor accepts three parameters that define the handler's execution context:

Parameter	Type	Purpose
$middlewares	array	Array of middleware to execute before core middleware
$coreMiddleware	mixed	The final middleware that dispatches to application handlers
$container	ContainerInterface	PSR-11 container for dependency resolution

class_map/HttpRequestHandler.php16-21

Diagram: HttpRequestHandler Class Structure

Sources: class_map/HttpRequestHandler.php14-21

---

Request Handling Flow

The handle() Method

The handle() method is the sole public interface defined by PSR-15's RequestHandlerInterface. It orchestrates the complete request processing lifecycle through three distinct operations:

class_map/HttpRequestHandler.php23-32

Operation 1: Context Storage

Context::set('request.middleware', $this->middlewares);

class_map/HttpRequestHandler.php25

The handler stores the middleware array in Hyperf's Context system using the key 'request.middleware'. This makes the middleware configuration accessible to other components during request processing. The Context class provides request-scoped data storage that survives across coroutine boundaries in Swoole's asynchronous environment.

Operation 2: Pipeline Resolution

$this->container->get(Pipeline::class)

class_map/HttpRequestHandler.php27-28

The handler retrieves the Pipeline instance from the dependency injection container. This ensures the Pipeline is properly instantiated with all its dependencies injected.

Operation 3: Pipeline Execution

->send($request)
->through([...$this->middlewares, $this->coreMiddleware])
->thenReturn();

class_map/HttpRequestHandler.php29-31

The pipeline is configured and executed through a fluent interface:

• send($request) - Sets the PSR-7 ServerRequestInterface as the payload to be processed
• through([...$this->middlewares, $this->coreMiddleware]) - Defines the middleware chain using the spread operator to flatten the middleware array and append the core middleware
• thenReturn() - Executes the pipeline and returns the ResponseInterface

Sources: class_map/HttpRequestHandler.php23-32

---

Request Processing Sequence

The following diagram traces the execution flow through the handler's handle() method, showing the interaction between code entities:

Diagram: handle() Method Execution Flow

Sources: class_map/HttpRequestHandler.php23-32

---

Middleware Chain Composition

The handler composes the final middleware chain by combining application middleware with core middleware:

Diagram: Middleware Chain Composition

The spread operator (...) in class_map/HttpRequestHandler.php30 flattens the $middlewares array into individual elements before appending $coreMiddleware as the final element. This ensures the core middleware always executes last in the chain.

Sources: class_map/HttpRequestHandler.php30

---

Dependency Resolution

The handler relies on Hyperf's dependency injection container to resolve the Pipeline instance at runtime:

Component	Resolution Method	Purpose
Pipeline	$container->get(Pipeline::class)	Retrieves configured pipeline for middleware execution
Context	Static class access	Stores request-scoped data
ServerRequestInterface	Passed as parameter	PSR-7 request object
ResponseInterface	Returned from pipeline	PSR-7 response object

The container-based resolution ensures that:

• The Pipeline receives its own dependencies (container, context awareness)
• The system maintains loose coupling between components
• Components can be easily mocked or replaced for testing

Sources: class_map/HttpRequestHandler.php9-12 class_map/HttpRequestHandler.php27-28

---

Context Storage Mechanism

The storage of middleware configuration in context serves multiple purposes:

Diagram: Context Storage Access Pattern

By storing the middleware array at class_map/HttpRequestHandler.php25 the handler makes this information available to:

• Error handlers that need to understand the middleware context
• Logging systems that track middleware execution
• Debugging tools that inspect the request processing chain

Sources: class_map/HttpRequestHandler.php7 class_map/HttpRequestHandler.php25

---

PSR-15 Compliance

The class implements Psr\Http\Server\RequestHandlerInterface class_map/HttpRequestHandler.php12 which requires a single method:

public function handle(ServerRequestInterface $request): ResponseInterface

This compliance ensures:

• Standard Interface: The handler can be used anywhere a PSR-15 request handler is expected
• Type Safety: PHP 8.2+ type declarations enforce correct request and response types
• Interoperability: The handler integrates seamlessly with PSR-15 middleware from any vendor

The use of PSR-7 message interfaces (ServerRequestInterface and ResponseInterface) further ensures compatibility with the broader PHP ecosystem.

Sources: class_map/HttpRequestHandler.php10-12 class_map/HttpRequestHandler.php23 composer.json24

---

Integration with Configuration System

The handler is instantiated and configured by Hyperf's HTTP server based on the class mapping registered through ConfigProvider. The mapping instructs Hyperf to use this implementation instead of its default:

Diagram: Handler Registration and Instantiation

The framework provides the constructor parameters:

• $middlewares - From application middleware configuration
• $coreMiddleware - The routing/dispatching middleware
• $container - The framework's DI container instance

Sources: class_map/HttpRequestHandler.php16-21 composer.json34-37

---

Summary

The HttpRequestHandler class serves as a lightweight orchestration layer with three core responsibilities:

1. Context Management: Stores middleware configuration in Hyperf's context system
2. Pipeline Delegation: Retrieves and configures the Pipeline component
3. Execution Control: Initiates middleware chain execution and returns the response

The implementation is deliberately minimal, delegating the complex middleware resolution and execution logic to the Pipeline class (see Pipeline Implementation). This separation of concerns allows the handler to focus solely on request lifecycle orchestration while the pipeline handles the intricacies of middleware adaptation and execution.

Sources: class_map/HttpRequestHandler.php1-34