HTTP Request Handling

Purpose and Scope

This document provides an overview of the HTTP layer in the Hypervel Foundation framework, covering the request lifecycle from incoming HTTP requests to final responses. It describes the core components involved in processing HTTP requests: the HTTP Kernel, middleware system, form request validation, and exception handling.

For detailed information about specific subsystems, see:

• HTTP Kernel implementation and request lifecycle: HTTP Kernel and Request Lifecycle
• Middleware registration and execution: Middleware System
• Form validation and input casting: Form Request Validation and Casting
• Exception reporting and rendering: Exception Handling and Error Responses
• Testing HTTP requests: HTTP Request Testing

Overview

The HTTP layer sits between the Swoole server and the application's controllers. When a request arrives, it flows through several processing stages: initialization, middleware execution, routing/dispatch, controller execution, exception handling (if needed), and response emission.

The framework extends Hyperf's HTTP server infrastructure while adding Laravel-like request handling patterns including form requests, validation, authorization, and a rich exception handling system.

Core Components

The HTTP layer consists of four primary components that work together to process requests:

Sources: src/Http/Kernel.php src/Exceptions/Handler.php src/Exceptions/Contracts/ExceptionHandler.php

Component Responsibilities

Component	Class	Primary Responsibilities
HTTP Kernel	Hypervel\Foundation\Http\Kernel	Request initialization, middleware coordination, exception handling setup, uploaded file conversion
Exception Handler	Hypervel\Foundation\Exceptions\Handler	Exception reporting, rendering to responses, context building, error view resolution
Middleware System	Hypervel\Foundation\Http\Traits\HasMiddleware	Middleware registration, resolution, priority ordering, group management
Form Request	Hypervel\Validation\FormRequest	Input validation, authorization checks, input casting, validation error responses

Sources: src/Http/Kernel.php1-166 src/Exceptions/Handler.php47-878

Request Lifecycle

The following sequence shows how an HTTP request flows through the framework from Swoole server to final response:

Sources: src/Http/Kernel.php49-165 src/Exceptions/Handler.php264-450 src/Providers/FormRequestServiceProvider.php16-22

Request Processing Stages

1. Request Initialization

The Kernel::onRequest() method receives the raw Swoole request and response objects, then performs initialization:

• Waits for worker process to start via CoordinatorManager::until(Constants::WORKER_START)->yield()
• Initializes PSR-7 Request and Response objects
• Trims trailing slashes from URI paths (except for root /)
• Converts Hyperf UploadedFile instances to Hypervel UploadedFile instances with additional capabilities

Sources: src/Http/Kernel.php49-76

2. Middleware Execution

The kernel resolves and executes middleware in priority order:

1. Global middleware (applied to all routes)
2. Route-specific middleware (defined on individual routes)
3. Middleware groups (collections of middleware)

See Middleware System for details on registration and execution.

Sources: src/Http/Kernel.php78-82

3. Routing and Dispatch

The Hyperf dispatcher routes the request to the appropriate controller method. If the controller method has FormRequest parameters, they are automatically resolved and validated before the controller executes.

Sources: src/Providers/FormRequestServiceProvider.php18-21

4. Exception Handling

If any exception occurs during processing, the Handler class processes it:

1. Mapping: Exception may be mapped to a different type via registered mappers
2. Reporting: Exception is logged unless in the $dontReport list
3. Rendering: Exception is converted to an HTTP response (HTML or JSON)

Sources: src/Exceptions/Handler.php264-450

5. Response Emission

The final response is emitted to the client via Hyperf's response emitter. Lifecycle events are dispatched:

• RequestHandled - Dispatched immediately after response is ready
• RequestTerminated - Deferred event dispatched after response sent

Sources: src/Http/Kernel.php86-155

Exception Types and Handling

The exception handler provides special handling for common exception types:

Sources: src/Exceptions/Handler.php110-679

Exception Response Logic

Exception Type	Reported?	Default JSON Behavior	Default HTML Behavior
ValidationException	No	JSON with errors array	Redirect back with errors flashed to session
AuthenticationException	No	401 JSON response	Redirect to login route
AuthorizationException	No	403 or custom status	403 error view
ModelNotFoundException	No	404 JSON response	404 error view
TokenMismatchException	No	419 JSON response	419 error view
HttpException	No	Status code with message	Error view (e.g., errors::404)
Other exceptions	Yes	500 with details (if debug)	Debug page or generic 500 view

Sources: src/Exceptions/Handler.php110-779

Uploaded File Conversion

The kernel automatically converts Hyperf's UploadedFile instances to Hypervel's enhanced UploadedFile class, which provides additional methods compatible with Laravel's API:

The conversion is recursive, handling nested arrays of uploaded files properly.

Sources: src/Http/Kernel.php64-121

Configuration

The HTTP layer is configured through the application configuration file and environment variables:

Configuration Key	Purpose	Default
app.debug	Enable detailed error pages	false
app.env	Application environment	'production'
app.url	Base URL for the application	'http://localhost'
app.timezone	Default timezone	'UTC'
app.locale	Default locale	'en'

Sources: publish/app.php9-171

Debug Mode Behavior

When app.debug is true:

• Exceptions render with full stack traces and context
• JSON responses include exception class, file, line, and trace
• Detailed error pages are shown instead of generic error views
• Validation errors include more debugging information

When app.debug is false:

• Exceptions render generic error messages
• JSON responses contain only simple error messages
• Custom error views are used (from resources/views/errors/)
• Sensitive information is hidden from responses

Sources: src/Exceptions/Handler.php671-836

Integration Points

The HTTP layer integrates with other framework subsystems:

• Application Container (Application Container and Dependency Injection): Used for dependency injection in controllers, middleware, and exception handlers
• Service Providers (Service Providers and Application Lifecycle): FormRequestServiceProvider registers form request validation hooks
• Routing System: Resolves routes to controllers and determines middleware
• Validation System: Validates form requests before controller execution
• Session Management: Flashes validation errors to session for redirect responses
• Authentication System: Handles authentication exceptions and guards
• Event System: Dispatches RequestReceived, RequestHandled, and RequestTerminated events

Sources: src/Exceptions/Handler.php136-141 src/Providers/FormRequestServiceProvider.php1-23 src/Http/Kernel.php123-155