Request Handling

Purpose and Scope

The Request subsystem provides a comprehensive API for accessing and manipulating incoming HTTP request data. The Request class extends Hyperf's base request handling with type-safe input access, content negotiation, file upload handling, and integration with session, validation, and authentication systems.

This page provides an overview of the Request system architecture and capabilities. For detailed information on specific features, see:

• Request object instantiation and contracts: Page 2.1 - Request Object & Contract
• Input data retrieval and type conversion: Page 2.2 - Input & Data Access
• HTTP headers and content negotiation: Page 2.3 - Headers & Content Negotiation
• File upload handling: Page 2.4 - File Uploads
• URL and routing information: Page 2.5 - URL & Route Information
• Session, authentication, and validation: Page 2.6 - Session, Authentication & Validation

System Architecture

Class Hierarchy and Layering

Diagram: Request Class Hierarchy

Sources: src/Request.php31 src/Contracts/RequestContract.php18

The Request system is built on three layers:

Layer	Component	Purpose
PSR-7	ServerRequestInterface	Standard HTTP message interface
Hyperf	HyperfRequest, RequestInterface	Framework base request handling
Hypervel	Request, RequestContract	Enhanced API with type safety and integrations

The Request class at src/Request.php31 extends Hyperf\HttpServer\Request and implements RequestContract at src/Contracts/RequestContract.php18 providing full compatibility with PSR-7 and Hyperf while adding Hypervel-specific features.

Context Management and PSR-7 Integration

Diagram: Request Context Flow

Sources: src/Request.php971-984

The Request object retrieves the underlying PSR-7 request from RequestContext at src/Request.php971-984 The protected getRequest() method includes error handling:

Condition	Behavior
Context exists	Returns ServerRequestInterface from RequestContext::get()
Context missing	Throws RuntimeException with setup instructions
Type mismatch	Re-throws TypeError from context retrieval

Sources: src/Request.php971-984

Capability Areas

The Request class provides functionality organized into six major capability areas, each documented in detail in child pages:

1. Input and Data Access

Core Methods: input(), all(), only(), except(), has(), filled(), missing()

Type Conversion: boolean(), integer(), float(), string(), date(), enum(), collect()

Access request data from query parameters, POST data, and JSON payloads with automatic type conversion and dot-notation support. See Page 2.2 - Input & Data Access for details.

Sources: src/Request.php74-422 src/Contracts/RequestContract.php36-194

2. Headers and Content Negotiation

Core Methods: header(), headers(), bearerToken(), accepts(), prefers(), wantsJson(), expectsJson()

MIME Type Handling: getMimeType(), getMimeTypes(), getAcceptableContentTypes()

Parse HTTP headers, negotiate content types, and determine client capabilities. Integrates with AcceptHeader for quality-based content negotiation. See Page 2.3 - Headers & Content Negotiation for details.

Sources: src/Request.php446-789 src/Contracts/RequestContract.php219-352

3. File Uploads

Core Methods: allFiles(), file(), hasFile()

Access uploaded files as UploadedFile instances with validation, storage, and MIME type detection. See Page 2.4 - File Uploads for details.

Sources: src/Request.php48-51 src/Contracts/RequestContract.php20-30

4. URL and Route Information

Core Methods: url(), fullUrl(), root(), route(), routeIs(), segment(), segments()

Host/Port: getHost(), getHttpHost(), getPort(), getScheme(), isSecure()

Access URL components, route parameters, path segments, and scheme/host information. Integration with routing system via getDispatchedRoute(). See Page 2.5 - URL & Route Information for details.

Sources: src/Request.php214-751 src/Contracts/RequestContract.php104-323

5. Request Detection

Core Methods: isJson(), ajax(), pjax(), prefetch(), isRange(), method()

Detect request characteristics such as AJAX calls, JSON payloads, PJAX requests, prefetch hints, and HTTP range requests.

Sources: src/Request.php298-864 src/Contracts/RequestContract.php149-384

6. Service Integrations

Session: session(), hasSession() - Access SessionContract from DI container

Validation: validate() - Inline validation using ValidatorFactoryContract

Authentication: user(), setUserResolver(), getUserResolver() - User resolution via closure

URL Signatures: hasValidSignature(), hasValidRelativeSignature() - Verification via UrlGeneratorContract

These integrations provide seamless access to framework services. See Page 2.6 - Session, Authentication & Validation for details.

Sources: src/Request.php869-961 src/Contracts/RequestContract.php387-442

Data Flow and Architecture

Request Data Sources

Diagram: Request Data Retrieval

Sources: src/Request.php34-36 src/Request.php407-422 src/Request.php869-961 src/Request.php971-984

The Request class maintains minimal state, storing only the $userResolver closure at src/Request.php34-36 All request data is retrieved dynamically:

Data Source	Access Method	Example
Query parameters	RequestContext::get()->getQueryParams()	input('search')
POST data	RequestContext::get()->getParsedBody()	input('email')
Uploaded files	RequestContext::get()->getUploadedFiles()	allFiles()
Headers	RequestContext::get()->getHeaders()	header('Accept')
Server variables	RequestContext::get()->getServerParams()	server('REMOTE_ADDR')
Container services	ApplicationContext::getContainer()->get()	session(), validate()

Sources: src/Request.php407-422 src/Request.php971-984

Input Data Merging

Diagram: Input Data Aggregation in all() Method

Sources: src/Request.php407-422

The all() method at src/Request.php407-422 combines query parameters, POST data, and uploaded files using array_replace_recursive(), with files taking precedence over input data for conflicting keys.

Framework Service Integration

The Request class integrates with framework services through lazy resolution from the DI container. Services are accessed on-demand rather than injected at construction.

Diagram: Service Integration Pattern

Sources: src/Request.php869-882 src/Request.php889-894 src/Request.php926-961

Service	Access Methods	Implementation Details
Session	session(), hasSession()	Resolves SessionContract from container; hasSession() checks availability
Validation	validate()	Resolves ValidatorFactoryContract, validates all() input against rules
URL Generator	hasValidSignature(), hasValidRelativeSignature(), hasValidSignatureWhileIgnoring()	Resolves UrlGeneratorContract for signature verification
Authentication	user(), setUserResolver(), getUserResolver()	Uses stored closure, not container-based

Sources: src/Request.php34-36 src/Request.php869-882 src/Request.php889-894 src/Request.php899-921 src/Request.php926-961

Key Design Patterns

Contract-Based Design

The Request system uses interface-based programming to separate public API from implementation:

Sources: src/Contracts/RequestContract.php18 src/Request.php31

Application code depends on RequestContract at src/Contracts/RequestContract.php18 allowing the DI container to inject the Request implementation at src/Request.php31 This enables testing with mock implementations and future implementation changes without affecting application code.

Lazy Service Resolution

Services are resolved from the container only when needed, not at Request construction:

Pattern	Example	Benefit
Lazy resolution	ApplicationContext::getContainer()->get(SessionContract::class)	No session overhead if unused
Availability check	hasSession() checks container before session()	Graceful degradation
On-demand delegation	validate() delegates to ValidatorFactoryContract	Service not instantiated until validation needed

Sources: src/Request.php869-882 src/Request.php889-894

PSR-7 Compatibility

Diagram: PSR-7 Access Pattern

Sources: src/Request.php966-984

The getPsr7Request() method at src/Request.php966-969 provides access to the underlying ServerRequestInterface, enabling interoperability with PSR-7 and PSR-15 middleware. The protected getRequest() method at src/Request.php971-984 includes error handling for missing request context.

Summary

The Request handling system provides a comprehensive, type-safe API for accessing HTTP request data. Key characteristics include:

1. Layered Abstraction: Builds on PSR-7 and Hyperf foundations while adding framework-specific features
2. Contract-Based Design: Separates interface from implementation for testability and flexibility
3. Service Integration: Seamlessly integrates with validation, session, authentication, and URL generation
4. Type Safety: Provides type conversion methods with sensible defaults
5. Context Management: Uses Hyperf's context system for request lifecycle management
6. Minimal State: Relies on external services and PSR-7 data rather than internal caching

The subsequent sections (2.1-2.7) provide detailed documentation of specific request handling features and APIs.