Overview

The hypervel/http package provides the HTTP request and response handling layer for the Hypervel framework. It delivers Laravel-inspired HTTP abstractions built on top of Hyperf's asynchronous, Swoole-based web server capabilities.

This page introduces the package's purpose, positioning within the framework stack, and high-level capabilities. For architectural details about how components interact, see Architecture. For installation instructions and configuration, see Installation & Configuration.

---

Purpose and Positioning

The hypervel/http package serves as an adapter layer between application code and the Hyperf framework. It provides familiar, Laravel-style HTTP handling APIs while preserving Hyperf's async I/O performance characteristics through Swoole.

Framework Stack Position

Sources: composer.json1-54 ConfigProvider.php1-32 High-Level Diagrams

The package bridges the gap between Hyperf's performance-oriented, async architecture and Laravel's developer-friendly HTTP APIs. It implements PSR-7 (HTTP Messages) and PSR-15 (Middleware) standards for interoperability.

---

Core Capabilities

The package provides five primary capability areas, with importance scores derived from code analysis:

Capability	Key Components	Importance	Purpose
Request Handling	Request, RequestContract	48.11, 28.72	Input retrieval, type conversion, header parsing, file uploads
Response Generation	Response, ResponseContract	17.98, 4.39	JSON, views, files, streams, HTTP status codes
Middleware Pipeline	CoreMiddleware, HandleCors, ValidatePostSize	18.20, 18.25, 3.50	Request routing, CORS, pre-processing
Dependency Injection	RouteDependency	21.95	Automatic parameter resolution for controllers and closures
Resource Transformations	JsonResource, ResourceCollection	1.68	API response formatting and data transformation

The Request class (importance: 48.11) serves as the primary interface for HTTP request data. The RouteDependency system (importance: 21.95) handles automatic dependency resolution for route handlers. CoreMiddleware (importance: 18.20) and HandleCors (importance: 18.25) form the core middleware pipeline.

For detailed documentation on each area, see Request Handling, Response Generation, and Middleware & Routing.

Sources: High-Level Diagrams (Diagram 1, Diagram 2)

---

Package Components Map

This diagram maps high-level concepts to concrete code entities in the package:

Sources: ConfigProvider.php11-30 composer.json23-26 High-Level Diagrams (Diagram 2)

The ConfigProvider class ConfigProvider.php11-30 establishes dependency injection bindings:

• ResponseContract::class → Response::class
• ServerRequestInterface::class → Request::class (PSR-7)
• HyperfCoreMiddleware::class → CoreMiddleware::class (routing override)

---

Request/Response Lifecycle

The following diagram shows how an HTTP request flows through the package components using actual class and method names:

Sources: ConfigProvider.php7-19 High-Level Diagrams

Key execution points:

1. HandleCors and ValidatePostSize middleware process the request first
2. CoreMiddleware::dispatch() matches routes and returns status codes (FOUND, NOT_FOUND, METHOD_NOT_ALLOWED)
3. RouteDependency resolves controller method parameters from the DI container
4. Response::transferToResponse() standardizes various return types into PSR-7 responses

---

Package Dependencies

The package requires the following Hyperf components at version ~3.1.0:

Dependency	Purpose
hyperf/http-server	Core HTTP server and routing capabilities
hyperf/context	Coroutine-safe context management for request data
hyperf/collection	Fluent array/collection manipulation
hyperf/stringable	String manipulation utilities
hyperf/codec	JSON encoding/decoding
hyperf/contract	Interface contracts
hyperf/resource	JSON API resource transformation base

Optional dependencies:

• hypervel/session - Required for Request::session() method
• hypervel/validation - Required for Request::validate() method

Sources: composer.json28-42

---

Usage Context

Different parts of the package serve distinct purposes:

When to Use Request Features

The Request class (importance: 48.11) provides comprehensive HTTP request data access:

Feature	Methods	Use Case
Input Retrieval	input(), all(), only(), except(), collect()	Access form/query data
Type Conversion	boolean(), integer(), float(), string(), date(), enum()	Type-safe input parsing
File Uploads	file(), allFiles(), hasFile()	Handle uploaded files via UploadedFile
Headers	header(), hasHeader(), bearerToken()	Access HTTP headers
Content Negotiation	accepts(), prefers(), expectsJson(), wantsJson()	Determine response format
URL Information	url(), fullUrl(), path(), segments(), routeIs()	Extract URL components
Validation	validate(), filled(), missing(), hasAny()	Check input presence/validity
Session	session(), hasSession()	Access session data (requires hypervel/session)
Security	hasValidSignature(), getClientIp()	Validate signed URLs, detect client IP

See Request Handling for comprehensive documentation.

When to Use Response Features

The Response class (importance: 17.98) handles HTTP response generation:

Feature	Methods	Use Case
Basic Responses	make(), noContent()	Create text or empty responses
JSON Responses	json(), return JsonResource	API responses with data transformation
Views	view()	Render templates (requires hyperf/view-engine)
File Downloads	file(), download()	Serve files with optional streaming
Streaming	stream(), streamDownload()	Large response bodies, generated content
Range Requests	withRangeHeaders()	HTTP range/partial content support

See Response Generation for comprehensive documentation.

When to Use Middleware

The middleware pipeline processes requests before route handlers:

Middleware	Class	Configuration	Purpose
CORS	HandleCors (importance: 18.25)	config/autoload/cors.php	Cross-origin resource sharing
POST Size	ValidatePostSize (importance: 3.50)	PHP post_max_size	Reject oversized POST requests
Custom	Implement MiddlewareInterface	Route/global registration	Application-specific logic

See Middleware & Routing for comprehensive documentation.

Sources: High-Level Diagrams (Diagram 4, Diagram 5)

---

Key Design Principles

The package follows these architectural principles:

1. Contract-Based Design: All major components implement interfaces (RequestContract, ResponseContract) for testability and extensibility

2. PSR Compliance: Implements PSR-7 for HTTP messages and PSR-15 for middleware, ensuring interoperability with PSR-compatible libraries

3. Coroutine Safety: Uses Hyperf's context management system to maintain request-scoped data safely across Swoole coroutines

4. Type Safety: Provides extensive type conversion methods and leverages PHP 8.2+ features for strongly-typed APIs

5. Extensibility: Supports method macro injection via Macroable trait and provides hook points for custom behavior

Sources: ConfigProvider.php1-32 composer.json1-54 High-Level Diagrams