Overview

Purpose and Scope

Hypervel is a Laravel-compatible PHP framework built on the Hyperf/Swoole coroutine runtime. It provides familiar Laravel-style APIs and developer experience while leveraging Swoole's high-performance asynchronous I/O and coroutine capabilities. This document provides a high-level overview of Hypervel's architecture, component structure, and core design principles.

For detailed information about specific subsystems:

• Package organization and monorepo structure: see Package Structure and Monorepo Organization
• Hyperf integration details: see Hyperf Integration and Swoole Foundation
• Application bootstrapping: see Application Container and Lifecycle
• Service provider system: see Service Providers and Bootstrapping

Sources: composer.json1-286 src/foundation/src/Application.php1-688

Framework Identity and Design Philosophy

Hypervel is positioned as a bridge between Laravel's developer-friendly API design and Hyperf's coroutine-based performance architecture. The framework maintains version 0.3.18 and provides 23 modular component packages distributed as a monorepo.

Key Design Principles

Principle	Implementation	Benefit
Laravel API Compatibility	Matching method signatures and behavior	Minimal learning curve for Laravel developers
Coroutine Safety	Context-based request isolation	Thread-safe concurrent request handling
Dual Integration	ConfigProvider + ServiceProvider patterns	Seamless Hyperf framework integration
Modularity	Independent, replaceable packages	Flexible dependency management
Performance	Swoole runtime, connection pooling	High throughput without sacrificing usability

Sources: composer.json2-12 src/foundation/src/Application.php30-34

High-Level Architecture

Architecture Overview Diagram

This diagram shows how Hypervel sits between the application code and the Hyperf/Swoole runtime, using dual integration patterns to maintain both Laravel-style ergonomics and Hyperf's coroutine capabilities.

Sources: composer.json145-188 src/foundation/src/Application.php25-90 src/foundation/composer.json60-67

Monorepo Component Structure

Hypervel distributes its functionality across 23 independent packages within a single Git repository. Each package can be installed separately, though the monorepo approach simplifies dependency management and version synchronization.

Component Categories

Component Package Organization

Sources: composer.json24-88 composer.json145-188

Package Dependency Patterns

The monorepo uses Composer's replace mechanism to provide all packages from a single repository:

Core Dependencies	Description
hyperf/framework ~3.1.0	Base Hyperf framework
hyperf/engine ^2.10	Swoole/Swow coroutine engine
nesbot/carbon ^2.72.6	Date/time handling
laravel/serializable-closure ^1.3	Closure serialization for queues
guzzlehttp/guzzle ^7.8.2	HTTP client
monolog/monolog ^3.1	Logging infrastructure

Sources: composer.json98-144

Core Technical Concepts

Coroutine-Safe Request Isolation

Unlike traditional PHP frameworks that rely on process isolation, Hypervel runs in a long-lived Swoole server where multiple requests are handled concurrently within the same process using coroutines. This requires careful state management:

Request Isolation Comparison

The framework uses Hyperf\Context\Context to store request-specific data that must remain isolated across concurrent requests:

• Request object: Stored at ServerRequestInterface::class
• Parsed request data: Stored at 'http.request.parsedData'
• Session data: Managed per-coroutine
• Authenticated user: Isolated per request

Sources: src/http/src/Request.php971-984 src/foundation/src/Application.php25-26

Dual Integration Pattern

Hypervel implements two parallel integration systems to bridge Laravel-style APIs with Hyperf's dependency injection:

Dual Integration Architecture

ConfigProvider (Hyperf pattern):

• Located in each package at src/{package}/src/ConfigProvider.php
• Defines dependency injection bindings for Hyperf's container
• Returns arrays of dependencies, commands, listeners, etc.
• Automatically discovered via composer.json extra section

ServiceProvider (Laravel pattern):

• Located at src/{package}/src/{Package}ServiceProvider.php
• Provides register() method for binding services
• Provides boot() method for bootstrapping after all services registered
• Manually registered in application or via auto-discovery

Sources: composer.json239-270 composer.json272-278 src/foundation/composer.json60-67

Application Container and Service Resolution

The Hypervel\Foundation\Application class serves as the central dependency injection container and orchestrates the entire framework lifecycle:

Application Container Capabilities

The Application container registers 40+ core service aliases that map friendly names to concrete implementations:

Alias	Concrete Class	Purpose
app	Hypervel\Foundation\Application	Application container
cache	Hypervel\Cache\CacheManager	Cache factory
db	Hyperf\DbConnection\Db	Database manager
router	Hypervel\Router\Router	Route registration
request	Hypervel\Http\Request	Current HTTP request
auth	Hypervel\Auth\AuthManager	Authentication factory
queue	Hypervel\Queue\QueueManager	Queue factory
log	Hypervel\Log\LogManager	Logging manager

Sources: src/foundation/src/Application.php546-664 src/foundation/src/Contracts/Application.php1-207

Framework Lifecycle

Application Bootstrap and Request Lifecycle

The framework bootstraps once when the Swoole server starts and then handles multiple requests within the same process. Each request:

1. Creates isolated Context storage for request-specific data
2. Resolves services from the container (shared across requests)
3. Executes through the middleware pipeline
4. Dispatches to route handlers
5. Cleans up Context after response

Sources: src/foundation/src/Application.php118-129 src/foundation/src/Application.php398-416

Key Framework Features

PHP 8.2+ Type System

Hypervel requires PHP 8.2 or higher and leverages modern PHP features:

• Typed properties: All class properties use strict types
• Union types: Used extensively in parameter definitions
• Enums: First-class support via Request::enum() method
• Readonly properties: For immutable configuration objects
• Attributes: Used for route definitions and command metadata

Sources: composer.json99 src/http/src/Request.php122-133

Global Helper Functions

The framework provides Laravel-compatible global helper functions loaded via Composer's files autoloading:

File	Functions	Purpose
src/foundation/src/helpers.php	app(), config(), abort()	Core framework helpers
src/router/src/Functions.php	route(), url()	URL generation
src/cache/src/Functions.php	cache()	Cache access
src/auth/src/Functions.php	auth()	Authentication
src/support/src/helpers.php	Collection, string helpers	Utility functions

Sources: composer.json72-87

Compatibility and Migration Path

Hypervel aims for API compatibility with Laravel, making migration straightforward:

Compatible APIs:

• Eloquent ORM (models, relationships, query builder)
• Request/Response handling
• Routing (named routes, middleware, route groups)
• Service providers and facades
• Validation rules and error handling
• Cache, queue, and event systems

Key Differences:

• Requires explicit Context management for request-specific data
• Long-lived application (no bootstrap on each request)
• Coroutine-safe implementations required for concurrent operations
• ConfigProvider registration in addition to ServiceProvider

Sources: src/http/src/Request.php31-985 src/foundation/src/Application.php1-688

System Requirements

PHP: >= 8.2
Required Extensions: hash, json, mbstring, openssl, pdo
Swoole Engine: hyperf/engine ^2.10
Base Framework: hyperf/framework ~3.1.0

Sources: composer.json99-120 src/foundation/composer.json22-48

---

This overview establishes the foundational concepts required to understand Hypervel's architecture. The following sections of this wiki dive deeper into specific subsystems and implementation details.