HTTP Layer

The HTTP Layer provides the request/response processing infrastructure for Hypervel applications. It encompasses request handling, routing, middleware execution, and URL generation. This layer is built on top of Hyperf's HTTP server while providing Laravel-compatible APIs and coroutine-safe request isolation through Context.

For information about console commands and CLI interactions, see Console System. For database-related HTTP features like Eloquent model binding in routes, see Database and ORM.

Architecture Overview

The HTTP Layer consists of several interconnected systems that work together to process incoming HTTP requests and generate responses:

Sources: src/router/src/DispatcherFactory.php1-52 src/router/src/RouteCollector.php1-184 src/http/src/Request.php1-985 src/router/src/Router.php1-190

Core Components

Request Class

The Request class (src/http/src/Request.php31) extends Hyperf's request implementation with Laravel-compatible methods. It is stored in coroutine Context to ensure thread-safe isolation across concurrent requests.

Key Responsibilities:

• Input retrieval with type casting (boolean(), integer(), float(), string(), date(), enum())
• Input validation methods (filled(), missing(), exists())
• Content negotiation (wantsJson(), acceptsJson(), expectsJson())
• URL and routing information (fullUrl(), route(), segment())
• Integration with sessions, validation, and authentication
• Request manipulation (merge(), replace(), mergeIfMissing())

Key Methods:

Method Category	Methods	Purpose
Input Retrieval	input(), query(), post(), all(), only(), except()	Get request data
Type Casting	boolean(), integer(), float(), string(), date(), enum()	Type-safe input access
Validation	filled(), missing(), exists(), has(), validate()	Check input presence and validate
Collections	collect(), keys()	Work with input as collections
URL Info	url(), fullUrl(), root(), segment(), segments()	Access URL components
Content Type	wantsJson(), accepts(), isJson(), expectsJson()	Content negotiation
Authentication	user(), bearerToken()	Access authenticated user
Routing	route(), routeIs(), fullUrlIs()	Route information
Manipulation	merge(), replace(), mergeIfMissing()	Modify input data

Sources: src/http/src/Request.php31-985 src/http/src/Contracts/RequestContract.php1-442 tests/Http/RequestTest.php1-900

Router and Route Registration

The Router class (src/router/src/Router.php20) acts as a proxy to RouteCollector, providing a convenient API for route registration. It uses the __call() magic method (src/router/src/Router.php49-54) to forward method calls to the underlying RouteCollector.

Route Registration Methods:

Method	HTTP Methods	Description
get(route, handler, options)	GET	Register GET route
post(route, handler, options)	POST	Register POST route
put(route, handler, options)	PUT	Register PUT route
delete(route, handler, options)	DELETE	Register DELETE route
patch(route, handler, options)	PATCH	Register PATCH route
head(route, handler, options)	HEAD	Register HEAD route
options(route, handler, options)	OPTIONS	Register OPTIONS route
match(methods, route, handler, options)	Custom array	Register multiple methods
any(route, handler, options)	All methods	Register all HTTP methods
group(prefix, callback, options)	N/A	Group routes with common attributes

Sources: src/router/src/Router.php1-190 src/router/src/RouteCollector.php1-184 tests/Router/RouteCollectorTest.php1-327

Route Options and Features

Routes support various options that control their behavior:

Sources: src/router/src/RouteCollector.php53-81 src/router/src/RouteCollector.php104-113 tests/Router/RouteCollectorTest.php74-108

Dispatcher Factory and Lazy Loading

The DispatcherFactory (src/router/src/DispatcherFactory.php13) implements lazy route loading. Routes are not loaded until the first request is processed, ensuring that service providers have completed their boot phase and all route files have been registered.

Initialization Process:

1. DispatcherFactory is constructed during container setup (src/router/src/DispatcherFactory.php17-20)
2. RouteFileCollector starts with default route file (src/router/src/RouteFileCollector.php11-15)
3. Service providers call loadRoutesFrom() during boot to add additional route files (src/foundation/src/Support/Providers/RouteServiceProvider.php18-22)
4. On first request, getRouter() is called (src/router/src/DispatcherFactory.php39-50)
5. If not initialized, initRoutes() loads all route files (src/router/src/DispatcherFactory.php22-37)
6. Route files are required, executing registration code (src/router/src/DispatcherFactory.php33-36)

Sources: src/router/src/DispatcherFactory.php13-51 src/router/src/RouteFileCollector.php1-36 tests/Router/DispatcherFactoryTest.php86-121

Request Lifecycle

When an HTTP request arrives at the server, it goes through several stages before reaching the controller:

Sources: src/router/src/DispatcherFactory.php39-50 src/http/src/Request.php664-702 src/router/src/Router.php102-139

Route Handlers and Options

Routes can be defined with various handler types and configuration options:

Handler Types:

Handler Type	Example	Description
String (Class::method)	'UserController::index'	Controller class and method
Array (Class, method)	[UserController::class, 'index']	Fully qualified class reference
Closure	function (Request $request) { }	Anonymous function
Array with options	['uses' => 'UserController::index', 'as' => 'user.index']	Handler with inline options

Route Option Keys:

Option	Type	Description	Example
as	string	Route name for URL generation	'user.profile'
middleware	array	Middleware to execute	['auth', 'verified']
without_middleware	array	Middleware to exclude	['csrf']
prefix	string	URL prefix	'/api'
namespace	string	Handler class namespace	'App\\Http\\Controllers'

Sources: src/router/src/RouteCollector.php115-162 tests/Router/RouteCollectorTest.php264-298

Model Binding and Explicit Bindings

The Router supports automatic model binding and explicit parameter bindings:

Model Binding:

The Router stores model bindings in the $modelBindings array (src/router/src/Router.php29) and validates that the model class exists and extends Model (src/router/src/Router.php104-115).

Explicit Binding:

Explicit bindings use closures stored in $explicitBindings (src/router/src/Router.php36) for custom parameter resolution (src/router/src/Router.php120-123).

Sources: src/router/src/Router.php102-139

Named Routes and Route Introspection

Routes can be named for easy reference in URL generation and route checks:

Named Route Registration:

Named routes are stored in the namedRoutes array (src/router/src/RouteCollector.php18) mapping route names to their FastRoute data (src/router/src/RouteCollector.php70-72).

Route Introspection Methods:

Method	Return Type	Description
Router::current()	?DispatchedRoute	Get current dispatched route
Router::getCurrentRoute()	?DispatchedRoute	Alias for current()
Router::currentRouteName()	?string	Get current route name
Router::input(key, default)	mixed	Get route parameter value
RouteCollector::has(name)	bool	Check if named route exists
RouteCollector::getNamedRoutes()	array	Get all named routes

Request Route Methods:

Method	Description	Example
$request->route()	Get DispatchedRoute instance	$request->route()
$request->route('param')	Get specific parameter	$request->route('id')
$request->routeIs('pattern')	Check route name pattern	$request->routeIs('admin.*')

Sources: src/router/src/RouteCollector.php83-102 src/router/src/Router.php143-181 src/http/src/Request.php694-720 tests/Router/RouteCollectorTest.php200-243

Context-Based Request Isolation

All request data is stored in coroutine Context to ensure thread-safe isolation across concurrent requests. The Request class retrieves the PSR-7 request from Context (src/http/src/Request.php971-984):

This pattern ensures that each coroutine has its own isolated request data, preventing race conditions in concurrent request processing.

Sources: src/http/src/Request.php971-984 tests/Http/RequestTest.php36-43

Integration Points

The HTTP Layer integrates with several other framework components:

Component	Integration Point	Description
Validation	Request::validate()	Validate input against rules (src/http/src/Request.php889-894)
Session	Request::session()	Access session data (src/http/src/Request.php877-882)
Authentication	Request::user()	Get authenticated user (src/http/src/Request.php918-921)
URL Generation	Request::hasValidSignature()	Verify signed URLs (src/http/src/Request.php926-961)
Route Resolution	Request::route()	Access matched route (src/http/src/Request.php694-702)

Container Aliases:

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

• request → Hypervel\Http\Contracts\RequestContract
• response → Hypervel\Http\Contracts\ResponseContract
• router → Hypervel\Router\Router
• url → Hypervel\Router\Contracts\UrlGenerator

Sources: src/http/src/Request.php869-961 src/foundation/src/Application.php546-664