Introduction to Hypervel Foundation

Purpose and Scope

This document provides a high-level overview of the Hypervel Foundation package, its role as a Laravel-inspired framework built on top of Hyperf, and its core architectural patterns. This introduction covers the framework's design philosophy, primary components, and how they work together to provide a familiar development experience for Laravel developers while leveraging Hyperf's high-performance async capabilities.

For detailed information about specific subsystems, see:

• Framework architecture and design principles: Framework Architecture and Design Principles
• Package structure and dependencies: Package Structure and Dependencies
• Application container and dependency injection: Application Container and Dependency Injection
• HTTP request handling: HTTP Request Handling
• Console command system: Console Command System
• Testing framework: Testing Framework

Sources: composer.json1-77 src/Application.php1-35

What is Hypervel Foundation?

Hypervel Foundation is the core package of the Hypervel framework, providing a Laravel-like development experience on top of Hyperf's high-performance async runtime. The package version is currently 0.3.18 as defined in src/Application.php34

The Foundation package serves as the central orchestration layer that:

• Extends Hyperf's DI Container - The Hypervel\Foundation\Application class extends Hypervel\Container\Container src/Application.php25 which itself extends Hyperf's container with additional Laravel-compatible features
• Implements Service Container Pattern - Manages service registration, dependency injection, and application lifecycle through the Hypervel\Foundation\Contracts\Application interface src/Contracts/Application.php13
• Provides Dual-Kernel Architecture - Separate HTTP and Console kernels handle web requests and CLI commands respectively
• Establishes Laravel-Compatible APIs - Offers familiar methods like basePath(), configPath(), environment(), and isLocal() for developers migrating from Laravel

Sources: src/Application.php25-90 src/Contracts/Application.php1-207 composer.json2-10

Core Components Architecture

The following diagram maps the framework's natural language concepts to their concrete implementations in code:

Component Architecture Diagram

Key Implementation Details:

Component	Class/File	Primary Responsibility
Application Container	Hypervel\Foundation\Application	Central DI container and service orchestrator
Application Contract	Hypervel\Foundation\Contracts\Application	Interface defining application capabilities
Config Provider	Hypervel\Foundation\ConfigProvider	Hyperf integration point for package registration
Foundation Service Provider	FoundationServiceProvider	Registers core framework services
Global Helpers	src/helpers.php	Provides static facade functions like app(), config()
HTTP Kernel	Hypervel\Foundation\Http\Kernel	Processes incoming HTTP requests
Console Kernel	Hypervel\Foundation\Console\Kernel	Handles CLI command execution

Sources: src/Application.php25-90 src/Contracts/Application.php13-207 src/ConfigProvider.php18-47 composer.json52-67

Dual-Kernel Architecture

Hypervel Foundation implements a dual-kernel pattern, separating concerns between HTTP and console environments:

Kernel Responsibility Matrix

Aspect	HTTP Kernel	Console Kernel
Entry Point	Swoole HTTP Server request	Artisan CLI command
Primary Method	onRequest()	Command handler methods
Middleware	Global, route, group middleware	Command-specific middleware
Response Type	HTTP responses (JSON/HTML)	Console output
Context	Per-request coroutine context	Single process execution
Event Dispatching	Request lifecycle events	Command lifecycle events

Both kernels share:

• Access to the Application container for dependency injection
• Common exception handling through Hypervel\Foundation\Exceptions\Handler
• Event dispatcher for lifecycle hooks
• Configuration system

Sources: src/ConfigProvider.php24-26 High-level diagrams (Diagram 1 & 3)

Application Lifecycle

The application follows a structured initialization and request handling lifecycle:

Application Bootstrap Flow

Key Lifecycle Methods:

Method	Location	Purpose
__construct()	src/Application.php82-90	Initialize container and base bindings
setBasePath()	src/Application.php160-165	Configure application root directory
bootstrapWith()	src/Application.php118-129	Execute bootstrap classes in sequence
register()	src/Application.php311-345	Register service provider with container
boot()	src/Application.php398-416	Boot all registered service providers
booting()	src/Application.php435-438	Register callback before boot
booted()	src/Application.php443-450	Register callback after boot

Sources: src/Application.php82-450 src/Contracts/Application.php20-154

Integration with Hyperf

Hypervel Foundation integrates deeply with Hyperf while maintaining Laravel-like conventions:

Hyperf Integration Points

Configuration Provider Structure:

The ConfigProvider class at src/ConfigProvider.php18-47 returns an array with these keys:

Package Metadata in composer.json:

The composer.json60-72 file defines two integration points:

1. Hyperf Integration (extra.hyperf.config): Tells Hyperf to load ConfigProvider
2. Hypervel Integration (extra.hypervel.providers): Declares FoundationServiceProvider for automatic registration

Sources: src/ConfigProvider.php18-47 composer.json60-72

Key Design Patterns

Service Provider Pattern

Service providers are the primary mechanism for registering services. The Application tracks providers in:

• $serviceProviders array src/Application.php70 - Stores provider instances
• $loadedProviders array src/Application.php75 - Tracks loaded provider names

The register() method src/Application.php311-345 handles provider registration with automatic binding of the bindings property.

Facade Pattern via Global Helpers

The src/helpers.php file (loaded via composer.json57-58) provides global functions that delegate to the Application container, implementing the facade pattern. These functions provide static-like access to framework services.

Container Alias System

The Application registers 40+ container aliases in registerCoreContainerAliases() src/Application.php546-664 allowing services to be resolved by multiple identifiers:

This enables flexible service resolution where app('config'), app(ConfigInterface::class), and $container->get('config') all resolve to the same instance.

Path Resolution System

The Application provides dedicated path helper methods for framework directories:

Method	Default Location	Configuration Override
basePath()	Root directory	Set via constructor
path()	app/	Not configurable
configPath()	config/	Not configurable
databasePath()	database/	Not configurable
langPath()	lang/	Not configurable
publicPath()	public/	Not configurable
resourcePath()	resources/	Not configurable
viewPath()	resources/views/	Via view.config.view_path config
storagePath()	storage/	Not configurable

All path methods support optional sub-path arguments: app()->configPath('app.php') returns config/app.php.

Sources: src/Application.php170-252 src/Contracts/Application.php40-87

Framework Dependencies

Hyperf Components

The Foundation package depends on multiple Hyperf 3.1.x components:

Component	Purpose
hyperf/di	Dependency injection container
hyperf/config	Configuration management
hyperf/command	Console command infrastructure
hyperf/http-server	HTTP server and routing
hyperf/database	Database query builder and ORM
hyperf/framework	Core framework utilities
symfony/error-handler	Enhanced error handling

Hypervel Packages

Foundation depends on other Hypervel packages for specific functionality:

Package	Purpose
hypervel/core	Core utilities and interfaces
hypervel/filesystem	File and storage operations
hypervel/support	Helper classes and service providers
hypervel/http	HTTP request/response abstractions
hypervel/validation	Input validation system

Sources: composer.json22-48

Environment Detection

The Application delegates environment detection to the Hypervel\Support\Environment service:

Method	Location	Purpose
environment()	src/Application.php259-266	Get or check environment name
detectEnvironment()	src/Application.php287-290	Detect current environment
isLocal()	src/Application.php271-274	Check if local environment
isProduction()	src/Application.php279-282	Check if production environment
runningUnitTests()	src/Application.php295-298	Check if testing environment
hasDebugModeEnabled()	src/Application.php303-306	Check if debug mode enabled

These methods provide Laravel-compatible APIs for environment-based logic.

Sources: src/Application.php259-306 src/Contracts/Application.php90-119

Locale Management

The Application provides internationalization support through translator integration:

Method	Purpose
getLocale() / currentLocale()	Retrieve current locale from translator
getFallbackLocale()	Get fallback locale
setLocale()	Set locale and dispatch LocaleUpdated event
isLocale()	Check if current locale matches

When setLocale() is called src/Application.php536-541 it:

1. Updates the translator service
2. Dispatches Hypervel\Foundation\Events\LocaleUpdated event src/Events/LocaleUpdated.php7-15

Sources: src/Application.php504-541 src/Events/LocaleUpdated.php7-15 src/Contracts/Application.php177-199

Built-in Commands

Foundation provides essential CLI commands registered through ConfigProvider:

Command	Class	Purpose
server:reload	ServerReloadCommand	Gracefully reload Swoole workers
about	AboutCommand	Display framework information
config:show	ConfigShowCommand	Show configuration values
vendor:publish	VendorPublishCommand	Publish package assets

The server:reload command src/Console/Commands/ServerReloadCommand.php14-71 sends SIGUSR1 and SIGUSR2 signals to reload workers and task workers respectively.

Sources: src/ConfigProvider.php31-36 src/Console/Commands/ServerReloadCommand.php14-71

Application Version

The framework version is defined as a class constant:

Accessible via Application::VERSION or the version() method src/Application.php100-103

Sources: src/Application.php34-103

Next Steps

For deeper understanding of specific subsystems:

• Application container mechanics: See Application Container and Dependency Injection
• Bootstrap process details: See Bootstrap Process and Service Registration
• HTTP request lifecycle: See HTTP Kernel and Request Lifecycle
• Testing infrastructure: See Test Case Foundation and Lifecycle
• Service provider system: See Service Providers and Application Lifecycle