Request Lifecycle and Processing

This document describes how HTTP requests are received, processed, and made available to application code in Hypervel. It covers the Request class, coroutine-safe context isolation, input retrieval methods, and integration with validation, sessions, and authentication systems.

For information about routing and dispatching requests to handlers, see Routing and Dispatching. For middleware execution, see Middleware Pipeline. For URL generation, see URL Generation and Signed URLs.

Overview

Hypervel's request handling is built on top of Hyperf's HTTP server and provides a Laravel-compatible API for accessing request data. The Request class (src/http/src/Request.php) extends Hyperf's base request class and adds extensive functionality for input retrieval, validation, session integration, and content negotiation. All request data is stored in coroutine-safe Context storage to ensure proper isolation in concurrent environments.

Request Object Architecture

The Request class implements the RequestContract interface and extends Hyperf's Request class, providing both PSR-7 compatibility and Laravel-style convenience methods.

Sources: src/http/src/Request.php31 src/http/src/Contracts/RequestContract.php18 src/support/src/Facades/Request.php144 src/foundation/src/Application.php597-601

Request Lifecycle

The following diagram illustrates the complete lifecycle of an HTTP request from reception to handler execution:

Sources: src/http/src/Request.php971-984 src/foundation/src/Application.php597-607

Context-Based Request Isolation

Hypervel uses Hyperf's Context storage to maintain request isolation across coroutines. Each concurrent request operates in its own coroutine with independent context storage.

Context Storage Keys

The Request class stores data in specific context keys:

Context Key	Content	Purpose
ServerRequestInterface::class	PSR-7 request object	Base request data
http.request.parsedData	Parsed input array	Combined query, body, and file data
RequestContext	Current request instance	Request context helper access

Retrieving the PSR-7 Request

The Request class retrieves the underlying PSR-7 request from context storage:

Sources: src/http/src/Request.php971-984

Context Manipulation Methods

The Request class provides methods to modify context data:

• merge(array $input) - Merges new input into existing data using Context::override() (src/http/src/Request.php335-343)
• replace(array $input) - Replaces specific input values using Context::override() (src/http/src/Request.php350-358)
• mergeIfMissing(array $input) - Merges only missing keys (src/http/src/Request.php365-372)

These methods modify the http.request.parsedData context key to ensure changes are visible within the current coroutine.

Sources: src/http/src/Request.php335-372

Input Retrieval Methods

The Request class provides extensive methods for accessing input data with type conversion and validation.

Basic Input Access

Method	Return Type	Description
input($key, $default)	mixed	Get input value with optional default
query($key, $default)	mixed	Get query string parameter
post($key, $default)	mixed	Get POST body parameter
all($keys)	array	Get all input (including files)
only($keys)	array	Get only specified keys
except($keys)	array	Get all except specified keys

Sources: src/http/src/Request.php407-422 src/http/src/Request.php387-402 src/http/src/Request.php140-148

Type-Safe Input Retrieval

The Request class provides type-casting methods for safe input handling:

Implementation details:

• boolean() - Uses FILTER_VALIDATE_BOOLEAN filter, returns true for "1", "true", "on", "yes" (src/http/src/Request.php74-80)
• integer() - Casts to int with default value support (src/http/src/Request.php278-281)
• float() - Casts to float with default value support (src/http/src/Request.php177-180)
• string() - Returns Stringable instance for fluent string manipulation (src/http/src/Request.php185-188)
• date() - Parses to Carbon instance with format and timezone support (src/http/src/Request.php101-112)
• enum() - Uses tryFrom() for PHP 8.1+ backed enums (src/http/src/Request.php122-133)
• collect() - Wraps input in Collection for functional operations (src/http/src/Request.php85-94)

Sources: src/http/src/Request.php74-133 src/http/src/Request.php177-188 src/http/src/Request.php278-281

Input Presence and Validation Checks

The Request class provides methods to check input presence and emptiness:

Presence Check Methods

Method	Behavior	Use Case
has($keys)	Key exists (inherited from Hyperf)	Check if input was sent
exists($keys)	Alias of has()	Laravel compatibility
missing($keys)	Inverse of has()	Check if input was not sent
filled($keys)	Key exists and non-empty	Validate required fields
isNotFilled($keys)	Key missing or empty	Check for empty values
anyFilled($keys)	At least one key is filled	OR validation
hasAny($keys)	At least one key exists	OR presence check

Empty String Detection

The isEmptyString() method determines if a value is considered empty for the filled() check:

Sources: src/http/src/Request.php286-293 src/http/src/Request.php161-172 src/http/src/Request.php306-317 src/http/src/Request.php56-67

Conditional Processing

The Request class provides fluent conditional methods:

• whenHas() - Execute callback if key exists, with optional default callback (src/http/src/Request.php572-583)
• whenFilled() - Execute callback if key is filled, with optional default callback (src/http/src/Request.php554-565)

Sources: src/http/src/Request.php152-380

File Upload Handling

File uploads are accessed through PSR-7 UploadedFileInterface instances:

• allFiles() - Returns all uploaded files from getUploadedFiles() (src/http/src/Request.php48-51)
• file($key) - Inherited from Hyperf, retrieves specific file
• hasFile($key) - Inherited from Hyperf, checks if file was uploaded

Files are merged with regular input in the all() method using array_replace_recursive() (src/http/src/Request.php407-422).

Sources: src/http/src/Request.php48-51 src/http/src/Request.php407-422

Request Introspection

URL and Path Methods

The Request class provides comprehensive URL introspection:

Method	Returns	Example
url()	Base URL without query	http://example.com/path
fullUrl()	URL with query string	http://example.com/path?foo=bar
root()	Scheme and host	https://example.com:8080
path()	URL path	/path/to/resource
segments()	Path segments array	['path', 'to', 'resource']
segment($index)	Specific segment (1-indexed)	segment(1) returns 'path'

Advanced URL methods:

• fullUrlWithQuery(array $query) - Adds query parameters to current URL (src/http/src/Request.php638-645)
• fullUrlWithoutQuery($keys) - Removes query parameters from current URL (src/http/src/Request.php650-659)
• uri() - Returns Uri instance for fluent manipulation (src/http/src/Request.php748-751)

Sources: src/http/src/Request.php615-660 src/http/src/Request.php672-687 src/http/src/Request.php748-751

Route Information

The Request class integrates with the routing system:

Route methods:

• route() - Returns DispatchedRoute object (src/http/src/Request.php694-702)
• route($param) - Returns specific route parameter value (src/http/src/Request.php694-702)
• routeIs(...$patterns) - Checks if route name matches patterns using Str::is() (src/http/src/Request.php707-720)
• fullUrlIs(...$patterns) - Checks if full URL matches patterns (src/http/src/Request.php725-735)

Sources: src/http/src/Request.php664-667 src/http/src/Request.php694-735

HTTP Method and Headers

Host and scheme information:

• getHost() - Extracts hostname from HOST header, removing port (src/http/src/Request.php214-219)
• getHttpHost() - Returns host with port (src/http/src/Request.php226-229)
• getPort() - Parses port from HOST header or defaults based on scheme (src/http/src/Request.php239-256)
• getScheme() - Returns 'http' or 'https' (src/http/src/Request.php261-265)
• isSecure() - Checks if scheme is 'https' (src/http/src/Request.php270-273)
• getSchemeAndHttpHost() - Combines scheme and host (src/http/src/Request.php430-433)

Sources: src/http/src/Request.php214-273 src/http/src/Request.php430-441

Client Information

• ip() / getClientIp() - Returns client IP from x-real-ip header or remote_addr (src/http/src/Request.php591-612)
• bearerToken() - Extracts Bearer token from Authorization header (src/http/src/Request.php764-777)
• method() - Returns HTTP method (GET, POST, etc.) (src/http/src/Request.php740-743)

Sources: src/http/src/Request.php591-612 src/http/src/Request.php740-743 src/http/src/Request.php764-777

Content Negotiation

The Request class provides extensive content negotiation support for REST APIs:

Accept Header Processing

Content negotiation methods:

• accepts($contentTypes) - Checks if client accepts any of the given types, supports wildcards (src/http/src/Request.php465-488)
• prefers($contentTypes) - Returns the most preferred type from options (src/http/src/Request.php493-519)
• acceptsJson() - Shortcut for accepts('application/json') (src/http/src/Request.php536-539)
• acceptsHtml() - Shortcut for accepts('text/html') (src/http/src/Request.php544-547)
• wantsJson() - Checks if first Accept type contains '/json' or '+json' (src/http/src/Request.php455-460)
• expectsJson() - Returns true if AJAX request without PJAX or wants JSON (src/http/src/Request.php446-450)

Sources: src/http/src/Request.php446-547

Request Type Detection

• isJson() - Checks if Content-Type contains '/json' or '+json' (src/http/src/Request.php298-301)
• ajax() / isXmlHttpRequest() - Checks for 'XMLHttpRequest' in X-Requested-With header (src/http/src/Request.php817-830)
• pjax() - Checks for X-PJAX header (src/http/src/Request.php835-838)
• prefetch() - Checks for prefetch headers (X-MOZ, Purpose, Sec-Purpose) (src/http/src/Request.php843-848)
• isRange() - Checks for valid Range header (src/http/src/Request.php853-864)

Sources: src/http/src/Request.php298-301 src/http/src/Request.php817-864

MIME Type Mapping

• getMimeType($format) - Returns MIME type for format string (e.g., 'json' → 'application/json') (src/http/src/Request.php794-797)
• getMimeTypes($format) - Returns all MIME types for format (src/http/src/Request.php804-807)
• getAcceptableContentTypes() - Returns sorted array of acceptable types from Accept header (src/http/src/Request.php784-789)

Sources: src/http/src/Request.php784-807

Session Integration

The Request class provides seamless session access:

Session Methods

• hasSession() - Checks if session service is available in container (src/http/src/Request.php869-873)
• session() - Returns the current session instance from container (src/http/src/Request.php878-882)

The session is resolved from the application container using the SessionContract::class binding. This ensures the correct session instance is retrieved for the current coroutine context.

Sources: src/http/src/Request.php869-882

Validation Integration

The Request class provides direct validation support:

Inline Validation

Validation method:

This method:

1. Retrieves the validator factory from the container
2. Validates $this->all() against the provided rules
3. Returns validated data on success
4. Throws ValidationException on failure

Sources: src/http/src/Request.php889-894

Authentication Integration

The Request class supports authentication through a user resolver callback:

User Resolution

Authentication methods:

• setUserResolver(Closure $callback) - Sets the callback for resolving authenticated user (src/http/src/Request.php908-913)
• getUserResolver() - Returns the user resolver callback (src/http/src/Request.php899-903)
• user(?string $guard = null) - Calls resolver with optional guard name (src/http/src/Request.php918-921)

The user resolver is typically set by the authentication middleware to integrate with the Auth system. The callback receives an optional guard name and returns the authenticated user model or null.

Sources: src/http/src/Request.php899-921

Signed URL Verification

The Request class integrates with the URL generator for signed URL validation:

Signature Verification Methods

• hasValidSignature($absolute = true) - Verifies URL signature via UrlGenerator (src/http/src/Request.php926-931)
• hasValidRelativeSignature() - Verifies relative URL signature (src/http/src/Request.php936-941)
• hasValidSignatureWhileIgnoring($ignoreQuery, $absolute) - Verifies signature ignoring specific query parameters (src/http/src/Request.php946-951)
• hasValidRelativeSignatureWhileIgnoring($ignoreQuery) - Relative version with ignored parameters (src/http/src/Request.php956-961)

All signature methods delegate to the UrlGenerator which is resolved from the container. This enables middleware and controllers to easily verify that URLs haven't been tampered with.

Sources: src/http/src/Request.php926-961

Request Facade and Helper

The Request can be accessed through multiple mechanisms:

Access Methods

Method	Usage	Resolution
Dependency Injection	function (Request $request)	Container resolves RequestContract
Facade	Request::input('key')	Static proxy to container instance
Helper function	request('key')	Returns Request instance or value
Container	app('request')	Direct container resolution

Container Aliases:

The Application container registers multiple aliases for the Request (src/foundation/src/Application.php597-607):

• request
• Psr\Http\Message\ServerRequestInterface
• Hyperf\HttpServer\Contract\RequestInterface
• Hyperf\HttpServer\Request
• Hypervel\Http\Contracts\RequestContract

Sources: src/support/src/Facades/Request.php144-150 src/foundation/src/Application.php597-607

Complete Request API Reference

The following table summarizes all Request class methods organized by category:

Input Retrieval

Method	Purpose
input($key, $default)	Get input value
query($key, $default)	Get query parameter
post($key, $default)	Get POST value
all($keys = null)	Get all input including files
only($keys)	Get subset of input
except($keys)	Get all except specified keys
boolean($key, $default)	Get as boolean
integer($key, $default)	Get as integer
float($key, $default)	Get as float
string($key, $default)	Get as Stringable
date($key, $format, $tz)	Get as Carbon
enum($key, $enumClass)	Get as enum
collect($key)	Get as Collection

Input Manipulation

Method	Purpose
merge($input)	Merge new input
replace($input)	Replace input values
mergeIfMissing($input)	Merge only missing keys

Input Validation

Method	Purpose
has($keys)	Check if keys exist
exists($keys)	Alias of has()
missing($keys)	Check if keys missing
filled($keys)	Check if non-empty
isNotFilled($keys)	Check if empty
anyFilled($keys)	At least one filled
hasAny($keys)	At least one exists
isEmptyString($key)	Check if string is empty
whenHas($key, $callback)	Conditional on existence
whenFilled($key, $callback)	Conditional on filled

File Uploads

Method	Purpose
allFiles()	Get all uploaded files
file($key, $default)	Get specific file
hasFile($key)	Check if file exists

URL Information

Method	Purpose
url()	Get base URL
fullUrl()	Get URL with query string
fullUrlWithQuery($query)	Add query parameters
fullUrlWithoutQuery($keys)	Remove query parameters
root()	Get scheme and host
path()	Get URL path
segments()	Get path segments
segment($index, $default)	Get specific segment
uri()	Get Uri instance

Route Information

Method	Purpose
route($param, $default)	Get route or parameter
routeIs(...$patterns)	Check route name
fullUrlIs(...$patterns)	Check full URL pattern
getDispatchedRoute()	Get DispatchedRoute object

HTTP Information

Method	Purpose
method()	Get HTTP method
getHost()	Get hostname
getHttpHost()	Get host with port
getPort()	Get port number
getScheme()	Get http/https
isSecure()	Check if HTTPS
getSchemeAndHttpHost()	Get scheme://host:port
ip() / getClientIp()	Get client IP
bearerToken()	Get Bearer token
headers()	Get all headers
header($key, $default)	Get specific header

Content Negotiation

Method	Purpose
isJson()	Check if JSON content
wantsJson()	Check if JSON requested
expectsJson()	Probably expects JSON
accepts($types)	Check if accepts types
prefers($types)	Get preferred type
acceptsJson()	Check if accepts JSON
acceptsHtml()	Check if accepts HTML
acceptsAnyContentType()	Accepts anything
getAcceptableContentTypes()	Get Accept header types
getMimeType($format)	Get MIME for format
getMimeTypes($format)	Get all MIMEs for format

Request Type Detection

Method	Purpose
ajax() / isXmlHttpRequest()	Check if AJAX
pjax()	Check if PJAX
prefetch()	Check if prefetch
isRange()	Check if range request

Integration

Method	Purpose
hasSession()	Check if session available
session()	Get session instance
validate($rules, $messages, $attributes)	Validate input
user($guard)	Get authenticated user
getUserResolver()	Get user resolver callback
setUserResolver($callback)	Set user resolver
hasValidSignature($absolute)	Verify URL signature
hasValidRelativeSignature()	Verify relative signature
hasValidSignatureWhileIgnoring($ignore, $absolute)	Verify with ignored params
hasValidRelativeSignatureWhileIgnoring($ignore)	Relative with ignored params

PSR-7 Compatibility

Method	Purpose
getPsr7Request()	Get underlying PSR-7 request

Sources: src/http/src/Request.php src/http/src/Contracts/RequestContract.php src/support/src/Facades/Request.php