Installation & Setup

This document guides you through installing the hypervel/http package, integrating it with the Hyperf framework, and configuring its features. It covers dependency installation via Composer, automatic framework integration through the package discovery system, and publishing configuration files for customization.

For information about the overall architecture and how components interact, see Architecture & Components. For details on specific features like CORS handling, see CORS Middleware.

---

Prerequisites

The package requires the following environment:

Requirement	Version	Purpose
PHP	^8.2	Core language runtime
Hyperf Framework	~3.1.0	HTTP server and DI infrastructure
Swoole Extension	(via Hyperf)	Asynchronous network capabilities

Sources: composer.json28-37

---

Installation via Composer

Standard Installation

Install the package using Composer:

This command installs hypervel/http along with its required dependencies:

Dependency	Version	Role
hyperf/http-server	~3.1.0	Base HTTP server implementation
hyperf/collection	~3.1.0	Data structure utilities
hyperf/stringable	~3.1.0	String manipulation helpers
hyperf/codec	~3.1.0	Encoding/decoding operations
hyperf/context	~3.1.0	Request-scoped context management
hyperf/contract	~3.1.0	Framework contracts and interfaces
hyperf/resource	~3.1.0	JSON resource transformations
nesbot/carbon	^2.72.6	Date/time manipulation

Sources: composer.json28-37

Optional Dependencies

The package suggests additional packages for extended functionality:

Package	Purpose	Required By
hypervel/session	Session management via $request->session()	Session access methods in Request
hypervel/validation	Request validation via $request->validate()	Validation methods in Request

Sources: composer.json39-42

---

Framework Integration

Automatic Package Discovery

Diagram: Package Discovery and Integration Flow

Sources: composer.json46-49 src/ConfigProvider.php11-31

Hyperf automatically discovers the package through the extra.hyperf.config field in composer.json:

During application bootstrap, Hyperf:

1. Scans installed packages for the extra.hyperf.config field
2. Instantiates the specified ConfigProvider class
3. Invokes its __invoke() method to retrieve configuration
4. Applies the returned dependency bindings and settings

Sources: composer.json46-49

---

Dependency Registration

Diagram: ConfigProvider Dependency Bindings

Sources: src/ConfigProvider.php11-31

The ConfigProvider class registers three critical dependency bindings:

Contract/Interface	Implementation	Purpose
ResponseContract	Response	Response generation abstraction
ServerRequestInterface	Request	PSR-7 request implementation with Hypervel extensions
HyperfCoreMiddleware	CoreMiddleware	Replaces Hyperf's default request dispatcher

These bindings are returned in the dependencies array:

Sources: src/ConfigProvider.php15-20

Binding Implications

ResponseContract → Response: When controllers or middleware type-hint ResponseContract, the DI container injects an instance of Response. This enables response generation methods like json(), view(), and stream().

ServerRequestInterface → Request: When code type-hints the PSR-7 ServerRequestInterface, the container provides Hypervel's extended Request class, which includes additional methods for input access, file uploads, and content negotiation.

HyperfCoreMiddleware → CoreMiddleware: This binding overrides Hyperf's default request dispatcher with Hypervel's version, which adds:

• Enhanced dependency injection via RouteDependency
• Automatic DispatchedRoute context management
• Custom response header handling

Sources: src/ConfigProvider.php16-19

---

Configuration Publishing

CORS Configuration

The package includes a default CORS configuration template that can be published to your application:

Diagram: Configuration Publishing Process

Sources: src/ConfigProvider.php21-28 publish/cors.php1-35

Publishing Command

To publish the CORS configuration file:

This command copies the template from publish/cors.php1-35 to config/autoload/cors.php in your application directory. The destination path is defined in the ConfigProvider:

Sources: src/ConfigProvider.php21-28

CORS Configuration Structure

The published configuration file contains the following settings:

Setting	Default	Description
paths	['api/*', 'sanctum/csrf-cookie']	URL patterns to apply CORS
allowed_methods	['*']	HTTP methods allowed for CORS requests
allowed_origins	['*']	Origins permitted to access resources
allowed_origins_patterns	[]	Regex patterns for origin matching
allowed_headers	['*']	Request headers allowed in CORS requests
exposed_headers	[]	Response headers exposed to client scripts
max_age	0	Preflight response cache duration (seconds)
supports_credentials	false	Whether credentials (cookies, auth) are supported

Default Configuration:

Sources: publish/cors.php5-34

⚠️ Security Note: The default configuration uses wildcard (*) values for permissive development. In production, configure specific origins, methods, and headers to restrict access appropriately.

---

Post-Installation Verification

Verify Package Installation

Confirm the package is installed and discovered:

Expected output includes package version, description, and dependency list matching composer.json1-11

Verify Dependency Bindings

Check that the DI container has registered the bindings. Create a test route in config/routes.php:

Access the route to verify the ResponseContract resolves to Hypervel's Response class.

Verify CORS Configuration (Optional)

If you published the CORS configuration, verify it exists:

The file should exist if publishing was successful. Modify the settings as needed for your application's CORS requirements. For details on CORS functionality, see CORS Middleware.

Sources: src/ConfigProvider.php21-28 publish/cors.php1-35

---

Configuration Locations

Summary of Key File Locations:

File	Location	Purpose
Package definition	vendor/hypervel/http/composer.json	Package metadata and dependencies
Service provider	vendor/hypervel/http/src/ConfigProvider.php	Framework integration point
CORS template	vendor/hypervel/http/publish/cors.php	Default CORS configuration
Published CORS config	config/autoload/cors.php	Application-specific CORS settings

Sources: composer.json1-54 src/ConfigProvider.php1-31 publish/cors.php1-35

---

Next Steps

After installation and setup:

1. Review the architecture - See Architecture & Components to understand how the request/response pipeline works
2. Use Request objects - See Request Object & Contract for request handling
3. Generate responses - See Response Object & Contract for response creation
4. Configure CORS - See CORS Middleware for advanced CORS configuration
5. Implement routing - See Core Middleware & Request Lifecycle for routing details

The package is now integrated with your Hyperf application and ready to handle HTTP requests.