Request Object & Contract

Purpose and Scope

This document covers the Request class and RequestContract interface, which form the foundation of request handling in the Hypervel HTTP library. These components provide a Laravel-like interface for accessing HTTP request data while building upon Hyperf's request infrastructure.

The Request object serves as the primary touchpoint for accessing incoming HTTP request information, including input data, headers, files, routing information, and client metadata. This page focuses on the class structure, instantiation mechanism, and contract definition. For specific functionality areas, refer to:

• Input data access and type conversion: Input & Data Access
• Header parsing and content negotiation: Headers & Content Negotiation
• File upload handling: File Uploads
• URL and routing information: URL & Route Information
• Session, authentication, and validation: Session, Authentication & Validation

Sources: src/Request.php1-985 src/Contracts/RequestContract.php1-442

---

Class Hierarchy and Inheritance

The Request class follows a contract-driven design pattern, extending Hyperf's base request implementation while implementing a feature-rich interface.

Inheritance Structure:

Layer	Component	Purpose
PSR Standard	Psr\Http\Message\ServerRequestInterface	PSR-7 HTTP message interface for interoperability
Hyperf Framework	Hyperf\HttpServer\Contract\RequestInterface	Hyperf's request contract
Hyperf Base	Hyperf\HttpServer\Request (HyperfRequest)	Base implementation with context management
Hypervel Contract	Hypervel\Http\Contracts\RequestContract	Extended contract with Laravel-like methods
Hypervel Implementation	Hypervel\Http\Request	Concrete implementation with all features

The class is defined in the Hypervel\Http namespace and extends HyperfRequest while implementing RequestContract. This dual inheritance pattern ensures:

1. PSR-7 Compliance: The request object adheres to PHP-FIG standards via the base classes
2. Framework Integration: Full compatibility with Hyperf's HTTP server and middleware system
3. Enhanced API: Additional convenience methods defined in RequestContract

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

---

Context-Based Instantiation

Unlike traditional request objects that are constructed directly, Hypervel's Request relies on context management to work within Hyperf's coroutine-based server environment. This design ensures proper request isolation across concurrent requests in the long-running Swoole server process.

Context Management

The Request class does not store the PSR-7 request object as an instance property. Instead, it retrieves it from the context on each method call:

Context Retrieval Flow:

1. Storage: Hyperf stores the PSR-7 ServerRequestInterface in RequestContext at the start of each request
2. Lazy Resolution: When Request methods are called, they invoke getRequest() src/Request.php971-984
3. Context Lookup: The getRequest() method retrieves the request from RequestContext::get() src/Request.php974
4. Error Handling: If context is not set, a RuntimeException is thrown src/Request.php977-979

This approach ensures that each coroutine has its own request data without interference, which is critical for Swoole's concurrent request handling.

Sources: src/Request.php964-985

---

Request Contract Definition

The RequestContract interface extends Hyperf's RequestInterface and defines over 70 methods organized into functional categories. This contract serves as the public API that application code depends on.

Method Categories

The contract organizes request functionality into these primary categories:

Category	Method Count	Key Methods	Purpose
Input Access	~15	input(), all(), only(), except(), has(), filled(), missing()	Retrieve and filter input data
Type Conversion	~8	boolean(), integer(), float(), string(), date(), enum(), collect()	Convert input to specific types
URL & Routing	~12	url(), fullUrl(), route(), routeIs(), segment()	Access URL and routing information
Headers	~10	header(), accepts(), prefers(), getAcceptableContentTypes()	Read headers and negotiate content
Metadata	~8	method(), ip(), ajax(), isJson(), isSecure()	Determine request characteristics
Integration	~10	session(), user(), validate(), hasValidSignature()	Integrate with framework features
File Uploads	~3	allFiles(), file(), hasFile()	Access uploaded files

Sources: src/Contracts/RequestContract.php18-442

---

Contract vs Implementation Mapping

The Request class implements all methods defined in RequestContract, providing concrete implementations. The class also inherits methods from HyperfRequest, creating a comprehensive API surface.

Key Implementation Details

Type Conversion Methods: The Request class provides convenience methods for type-safe input retrieval:

• boolean(string $key, bool $default) src/Request.php74-80 - Uses FILTER_VALIDATE_BOOLEAN for conversion
• integer(string $key, int $default) src/Request.php278-281 - Casts to int
• float(string $key, float $default) src/Request.php177-180 - Casts to float
• string(string $key, mixed $default) src/Request.php185-188 - Returns Stringable instance
• date(string $key, ?string $format, ?string $tz) src/Request.php101-112 - Returns Carbon instance
• enum(string $key, $enumClass) src/Request.php122-133 - Returns enum instance via tryFrom()

Input Validation Methods: Several methods check for input presence and emptiness:

• filled(array|string $key) src/Request.php161-172 - Checks for non-empty values
• isEmptyString(string $key) src/Request.php286-293 - Determines if value is an empty string
• isNotFilled(array|string $key) src/Request.php306-317 - Inverse of filled()

User Resolution: The request supports dynamic user resolution via a callback pattern:

• Property: protected ?Closure $userResolver src/Request.php36
• Setter: setUserResolver(Closure $callback) src/Request.php908-913
• Getter: getUserResolver() src/Request.php899-903
• Usage: user(?string $guard) src/Request.php918-921 calls the resolver

Sources: src/Request.php31-985 src/Contracts/RequestContract.php18-442

---

PSR-7 Bridge

The Request class provides a bridge to the underlying PSR-7 request object, allowing direct access when needed for framework interoperability or low-level operations.

PSR-7 Access Methods

The class provides two methods for accessing the underlying PSR-7 request:

1. Public API: getPsr7Request(): ServerRequestInterface src/Request.php966-969

   • Public method defined in RequestContract
   • Calls protected getRequest() method
   • Returns the PSR-7 ServerRequestInterface

2. Internal Access: getRequest(): ServerRequestInterface src/Request.php971-984

   • Protected method for internal use
   • Retrieves request from RequestContext::get()
   • Includes error handling for missing context
   • Throws RuntimeException if context not set

This design allows application code to access PSR-7 features when necessary while maintaining the enhanced Hypervel API as the primary interface.

Sources: src/Request.php964-985

---

Dependency Injection Integration

The Request class integrates with Hyperf's dependency injection container through the ConfigProvider registration system. This enables automatic injection of the request object into controllers and services.

Registration Pattern

The request binding is registered via the package's ConfigProvider:

1. Interface Binding: RequestContract::class is bound to Request::class
2. Container Resolution: When a controller type-hints RequestContract, the container instantiates Request
3. Context Availability: The request context must be set before resolution (handled by Hyperf)

Usage in Controllers

Controllers can receive the request through constructor injection or method injection:

The type-hint can use either:

• Hypervel\Http\Contracts\RequestContract (recommended for contract-based programming)
• Hypervel\Http\Request (when concrete implementation features are needed)

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

---

Basic Usage Patterns

The Request object provides a fluent, expressive API for common request handling tasks. Below are fundamental usage patterns that demonstrate the contract's design.

Input Retrieval

Type-Safe Input

Presence Checking

Conditional Operations

URL and Routing

Request Characteristics

Sources: src/Request.php1-985 src/Contracts/RequestContract.php1-442