Last indexed: 7 February 2026 (a324f6)

Session, Authentication & Validation

This page documents the Request object's capabilities for session management, user authentication, request validation, and URL signature verification. These features enable secure request handling, user identification, input validation, and URL integrity checking.

For general request data access methods, see Input & Data Access. For information about route parameters and URL construction, see URL & Route Information.

Overview

The Request class provides four distinct security and state management subsystems:

Subsystem	Purpose	Primary Methods
Session Access	Retrieve and manage session data	`hasSession()`, `session()`
Authentication	Identify authenticated users	`user()`, `setUserResolver()`, `bearerToken()`
Validation	Validate request input data	`validate()`
URL Signatures	Verify signed URL integrity	`hasValidSignature()`, `hasValidRelativeSignature()`

These features integrate with external Hypervel packages through dependency injection, enabling flexible authentication strategies and validation rules.

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

Session Management

Session Availability Detection

The hasSession() method determines whether session functionality is available by checking if SessionContract is bound in the DI container. This allows graceful degradation when session functionality is not installed.

Implementation Details:

The method queries the Hyperf application container for the Hypervel\Session\Contracts\Session binding. If the binding exists, session operations are available; otherwise, applications must handle requests without session support.

Sources: src/Request.php869-873 src/Contracts/RequestContract.php387-389

Accessing the Session

The session() method retrieves the session instance for the current request. This provides access to session storage operations like getting, setting, and deleting session data.

Error Handling:

The method directly resolves SessionContract from the container without checking availability first. If session functionality is not installed, this will throw a container resolution exception. Applications should call hasSession() first when session availability is uncertain.

Sources: src/Request.php878-882 src/Contracts/RequestContract.php391-394

Session Integration Architecture

Sources: src/Request.php869-882 src/Contracts/RequestContract.php387-394

Authentication System

The Request class provides a flexible authentication system based on a user resolver callback pattern. This design allows different authentication strategies without coupling the HTTP layer to specific authentication implementations.

User Resolver Pattern

Authentication is implemented through a resolver callback that can be set by authentication middleware or service providers. The callback receives an optional guard name and returns the authenticated user, or null if no user is authenticated.

Sources: src/Request.php34-36 src/Request.php899-921

Setting the User Resolver

The setUserResolver() method accepts a Closure that will be invoked when user() is called. This callback is stored in the protected $userResolver property src/Request.php36

Sources: src/Request.php908-913 src/Contracts/RequestContract.php409-411

Retrieving the Authenticated User

The user() method invokes the user resolver callback with the optional guard parameter. If no resolver has been set, it returns the result of an empty closure (effectively null).

Sources: src/Request.php918-921 src/Contracts/RequestContract.php413-416

Bearer Token Extraction

The bearerToken() method extracts OAuth 2.0 bearer tokens from the Authorization header. This is commonly used for API authentication.

Parsing Logic:

Retrieves the Authorization header src/Request.php766
Finds the last occurrence of "Bearer " in the header src/Request.php768
Extracts the token substring after "Bearer " src/Request.php771
Handles comma-separated multiple tokens by returning only the first src/Request.php773

This implementation follows RFC 6750 for bearer token authentication.

Sources: src/Request.php764-777 src/Contracts/RequestContract.php330-333

Authentication Flow Diagram

Sources: src/Request.php899-921

Authentication Method Reference

Method	Purpose	Return Type	Notes
`setUserResolver(Closure $callback)`	Register authentication resolver	`static`	Typically called by middleware
`getUserResolver()`	Get current resolver	`Closure`	Returns empty closure if none set
`user(?string $guard = null)`	Get authenticated user	`mixed`	Invokes resolver with guard parameter
`bearerToken()`	Extract bearer token	`?string`	Parses Authorization header

Sources: src/Request.php764-777 src/Request.php899-921 src/Contracts/RequestContract.php330-333 src/Contracts/RequestContract.php404-416

Request Validation

The validate() method provides direct access to validation functionality from the request object, eliminating the need to manually retrieve the validator factory.

Basic Validation

Sources: src/Request.php889-894 src/Contracts/RequestContract.php396-401

Validation with Custom Messages

Implementation Details

The validate() method src/Request.php889-894 performs these operations:

Resolves ValidatorFactoryContract from the DI container src/Request.php891-892
Passes $this->all() as the data to validate src/Request.php893
Forwards $rules, $messages, and $customAttributes parameters src/Request.php893
Returns validated data array on success
Throws \Hypervel\Validation\ValidationException on failure

Data Source: The method validates all request input returned by all(), which includes query parameters, POST data, JSON payloads, and uploaded files merged together.

Sources: src/Request.php889-894 src/Contracts/RequestContract.php396-401

Validation Integration Architecture

Sources: src/Request.php889-894

URL Signature Verification

URL signature verification ensures that URLs have not been tampered with and were generated by the application. This is commonly used for temporary access links, email verification URLs, and password reset links.

Signature Verification Methods

The Request class provides four methods for verifying URL signatures, offering flexibility for different use cases:

Method	Checks Absolute URL	Can Ignore Query Params	Use Case
`hasValidSignature(bool $absolute = true)`	Yes (default)	No	Standard signed URLs
`hasValidRelativeSignature()`	No	No	Domain-agnostic signed URLs
`hasValidSignatureWhileIgnoring(array $ignoreQuery, bool $absolute)`	Configurable	Yes	URLs with additional tracking params
`hasValidRelativeSignatureWhileIgnoring(array $ignoreQuery)`	No	Yes	Relative URLs with extra params

Sources: src/Request.php926-961 src/Contracts/RequestContract.php418-436

Absolute URL Signatures

Absolute signature verification validates that the complete URL (including scheme and domain) matches the signature.

Use Cases:

Email verification links
Password reset URLs
One-time download links

Sources: src/Request.php926-931 src/Contracts/RequestContract.php418-421

Relative URL Signatures

Relative signature verification validates only the path and query string, ignoring the domain. This allows signed URLs to work across multiple domains (e.g., staging and production).

Use Cases:

Multi-domain applications
Development/staging/production URL portability
CDN-served content with signed URLs

Sources: src/Request.php936-941 src/Contracts/RequestContract.php423-426

Ignoring Query Parameters

When URLs contain additional tracking or analytics parameters that should not affect signature validity, use the "while ignoring" variants:

Use Cases:

URLs with Google Analytics parameters
Links with referral tracking
A/B testing parameters
Social media share identifiers

Sources: src/Request.php946-961 src/Contracts/RequestContract.php428-436

URL Signature Verification Flow

Sources: src/Request.php926-961

Implementation Architecture

All signature verification methods delegate to the UrlGeneratorContract:

Resolve UrlGeneratorContract from the application container src/Request.php928-929 src/Request.php938-939 src/Request.php948-949 src/Request.php958-959
Call hasValidSignature($request, $absolute, $ignoreQuery) on the generator src/Request.php930 src/Request.php940 src/Request.php950 src/Request.php960
Return the boolean validation result

The URL generator compares the signature query parameter against a computed HMAC of the URL components, using the application's secret key.

Sources: src/Request.php926-961 src/Contracts/RequestContract.php418-436

Signature Method Parameter Matrix

Sources: src/Request.php926-961

Method Summary

Refresh this wiki

URL: https://deepwiki.com/hypervel/http/2.6-session-authentication-and-validation