Architecture & Components

This document describes the high-level architecture of the Hypervel HTTP library, explaining how its core components interact to process HTTP requests and generate responses. It covers the layered system design, the request processing pipeline, and the relationship between major components including Request, Response, CoreMiddleware, and RouteDependency.

For specific implementation details on individual components:

• Request handling capabilities: see Request Object & Contract and Input & Data Access
• Response creation methods: see Response Object & Contract and Response Types
• Middleware pipeline details: see Core Middleware & Request Lifecycle
• Route parameter resolution: see Route Dependency Injection

---

System Architecture Overview

Hypervel HTTP is built as a layered architecture on top of the Hyperf framework, providing an enhanced HTTP abstraction layer that maintains PSR-7 and PSR-15 compliance while offering Laravel-style ergonomics.

Architectural Layers

Sources: src/Request.php31 src/Response.php26 src/CoreMiddleware.php34 src/RouteDependency.php16 src/DispatchedRoute.php10

Component Responsibilities

Layer	Components	Responsibilities
Application	Controllers, Custom Middleware	Business logic, route handling, application-specific request/response processing
Hypervel HTTP	Request, Response, CoreMiddleware, RouteDependency	Enhanced HTTP abstractions, routing coordination, dependency injection, content negotiation
Hyperf Framework	HTTP Server, DI Container, Context	Low-level HTTP handling, dependency management, request/response context isolation
PSR Standards	PSR-7, PSR-15	Standard HTTP message interfaces, middleware contract

Sources: src/Request.php1-985 src/Response.php1-443 src/CoreMiddleware.php1-203

---

Core Components

Request Component

The Request class extends Hyperf's HyperfRequest and implements RequestContract, serving as the primary interface for accessing incoming HTTP request data.

Key Features:

• Input retrieval with type conversion: Methods like boolean(), integer(), float(), string(), date(), enum(), collect() src/Request.php74-133
• Content negotiation: accepts(), prefers(), wantsJson(), expectsJson() src/Request.php465-546
• URL manipulation: url(), fullUrl(), fullUrlWithQuery(), fullUrlWithoutQuery() src/Request.php625-659
• Route information: route(), routeIs(), getDispatchedRoute() src/Request.php664-720
• Session and validation integration: session(), validate(), user() src/Request.php869-921

Sources: src/Request.php31-985

Response Component

The Response class extends Hyperf's HyperfResponse and implements ResponseContract, providing methods to create various types of HTTP responses.

Key Response Types:

• Basic responses: make() with content/status/headers src/Response.php162-184
• JSON responses: json() with automatic encoding src/Response.php220-228
• View responses: view() for template rendering src/Response.php202-213
• File responses: file() with MIME type detection src/Response.php233-255
• Streaming responses: stream() and streamDownload() for chunked transfer src/Response.php271-339
• HTTP range requests: withRangeHeaders() for partial content delivery src/Response.php344-423

HTTP Status Code Constants: The class defines all standard HTTP status codes from 100-511 src/Response.php28-152

Sources: src/Response.php26-443

CoreMiddleware Component

CoreMiddleware implements Hyperf's CoreMiddlewareInterface and serves as the central orchestrator for request routing and dispatching.

Responsibilities:

1. Route Matching: Dispatches requests to FastRoute dispatcher src/CoreMiddleware.php111-120
2. Handler Resolution: Determines whether route is a closure or controller action src/CoreMiddleware.php127-152
3. Dependency Injection: Uses RouteDependency to resolve method parameters src/CoreMiddleware.php130-145
4. Response Normalization: Converts non-standard responses (arrays, views, strings) to PSR-7 responses src/CoreMiddleware.php53-95
5. Error Handling: Throws appropriate HTTP exceptions for 404 and 405 scenarios src/CoreMiddleware.php185-202

Sources: src/CoreMiddleware.php34-203

RouteDependency Component

RouteDependency handles automatic dependency injection for route handler parameters, resolving dependencies from route parameters, the DI container, or default values.

Parameter Resolution Order:

1. Route parameters: Matched from URL pattern src/RouteDependency.php160
2. Default values: From method signature src/RouteDependency.php162-163
3. Container resolution: From DI container if type exists src/RouteDependency.php164-165
4. Nullable parameters: Null if parameter allows null src/RouteDependency.php166-167

After-Resolving Callbacks: Supports registering callbacks that execute after dependencies are resolved, useful for intercepting resolved instances src/RouteDependency.php51-101

Sources: src/RouteDependency.php16-176

DispatchedRoute Component

DispatchedRoute extends Hyperf's Dispatched class, providing enhanced access to matched route information.

Key Methods:

Method	Purpose	Source
isClosure()	Check if handler is a closure	src/DispatchedRoute.php24-27
isControllerAction()	Check if handler is a controller	src/DispatchedRoute.php32-35
getCallback()	Get the route callback	src/DispatchedRoute.php40-43
parameters()	Get all route parameters	src/DispatchedRoute.php48-51
parameter()	Get specific route parameter	src/DispatchedRoute.php56-59
getName()	Get route name	src/DispatchedRoute.php80-83
getMiddleware()	Get route middleware	src/DispatchedRoute.php87-91
getControllerClass()	Get controller class name	src/DispatchedRoute.php96-99
getControllerCallback()	Get parsed controller callback	src/DispatchedRoute.php104-107

Sources: src/DispatchedRoute.php10-108

---

Request Processing Pipeline

The following sequence diagram illustrates the complete flow from receiving an HTTP request to sending a response.

Request Lifecycle Sequence

Sources: src/CoreMiddleware.php111-202 src/RouteDependency.php108-175

---

Component Dependency Graph

This diagram shows how core components depend on each other and external dependencies.

Component Dependencies

Sources: src/Request.php1-31 src/Response.php1-26 src/CoreMiddleware.php1-46 src/RouteDependency.php1-46 src/DispatchedRoute.php1-10 src/StreamOutput.php1-14

---

Request Context and State Management

Hypervel HTTP leverages Hyperf's context management system to maintain request-scoped state in the long-running Swoole/Swow server environment.

Context Architecture

Context Usage Patterns:

1. Request Storage: RequestContext::set($request) stores the current PSR-7 request src/Request.php971-984
2. Response Storage: ResponseContext::get() retrieves the current PSR-7 response src/CoreMiddleware.php100-103
3. Container Access: ApplicationContext::getContainer() provides DI container access src/Request.php871-882
4. Request Attributes: Route information stored in request attributes via setAttribute() src/CoreMiddleware.php118-120

Sources: src/Request.php971-984 src/Response.php100-103 src/CoreMiddleware.php100-120

---

Response Type Transformation

CoreMiddleware normalizes various return types from controllers into standard PSR-7 responses.

Supported Return Types

Return Type	Transformation	Content-Type	Source
Renderable / ViewInterface	Render template to string	From RenderInterface	src/CoreMiddleware.php55-66
string	Wrap in response body	text/plain	src/CoreMiddleware.php68-70
ResponseInterface	Use as-is (already PSR-7)	Unchanged	src/CoreMiddleware.php72-74
array / Arrayable	JSON encode	application/json	src/CoreMiddleware.php76-80
Jsonable	Call __toString()	application/json	src/CoreMiddleware.php82-86
Other types	Cast to string	text/plain or existing	src/CoreMiddleware.php88-94

Transformation Flow:

Sources: src/CoreMiddleware.php53-95 src/CoreMiddleware.php175-180

---

Streaming Response Architecture

For large file downloads and chunked responses, the Response class provides streaming capabilities.

Streaming Components

Streaming Features:

1. Manual Header Sending: Headers sent before content streaming begins src/Response.php299-306
2. Callback-Based Writing: User callback receives StreamOutput for writing chunks src/Response.php308-311
3. Download Headers: streamDownload() sets appropriate headers for file downloads src/Response.php323-338
4. Range Request Support: withRangeHeaders() enables partial content delivery src/Response.php344-423

Sources: src/Response.php271-339 src/StreamOutput.php9-20

---

Summary of Key Architectural Decisions

Design Principles

1. PSR Compliance: All HTTP messages implement PSR-7 interfaces, middleware follows PSR-15
2. Framework Extension: Extends Hyperf base classes rather than replacing them
3. Contract-Based: Interfaces separate contracts from implementations for testability
4. Context Isolation: Request/response stored in context for proper isolation in long-running servers
5. Type Safety: Extensive use of type hints and automatic parameter resolution
6. Flexible Responses: Automatic normalization of various return types to PSR-7

Component Interaction Summary

Component	Interacts With	Purpose of Interaction
Request	RequestContext, ApplicationContext	Retrieve PSR-7 request, access DI container
Response	ResponseContext, RequestContext	Retrieve PSR-7 response, check for range headers
CoreMiddleware	Request, Response, RouteDependency, DispatchedRoute	Orchestrate request lifecycle
RouteDependency	Container, Normalizer, Definition Collectors	Resolve method parameters with DI
DispatchedRoute	Hyperf's Dispatched	Enhance route information access

Sources: src/Request.php1-985 src/Response.php1-443 src/CoreMiddleware.php1-203 src/RouteDependency.php1-176 src/DispatchedRoute.php1-108