Framework Architecture and Design Principles

Purpose and Scope

This document explains the architectural design of Hypervel Foundation, a Laravel-style framework layer built on top of Hyperf. It covers the framework's layered architecture, core design patterns (dependency injection, service providers, facades), and how these components work together to provide a familiar Laravel API while leveraging Hyperf's high-performance async capabilities.

For detailed information about specific subsystems, see: Package Structure and Dependencies, Application Container and Dependency Injection, Service Providers and Application Lifecycle, and Configuration System and Config Provider.

---

Layered Architecture Overview

Hypervel Foundation employs a three-layer architecture that bridges Laravel-style development patterns with Hyperf's high-performance async runtime.

Architecture Layers

Sources: src/Application.php25 src/Http/Kernel.php28 src/Console/Kernel.php32 src/ConfigProvider.php20-46

The Hypervel Framework Layer provides Laravel-compatible APIs and conventions, making Hyperf development familiar to Laravel developers. The Hyperf Framework Layer supplies the underlying async-capable components (DI container, event system, database connections, HTTP server). The PHP/Swoole Infrastructure Layer provides the runtime environment and core PHP functionality.

---

Dual-Kernel Architecture

Hypervel Foundation implements a dual-kernel architecture to handle both HTTP requests and console commands through separate, specialized kernel classes.

Kernel Comparison

Aspect	HTTP Kernel	Console Kernel
Class	Hypervel\Foundation\Http\Kernel	Hypervel\Foundation\Console\Kernel
Extends	Hyperf\HttpServer\Server	None (direct implementation)
Entry Point	onRequest() method	handle() / run() methods
Bootstrap	Via Application bootstrap	Own bootstrap() method
Middleware	HTTP middleware pipeline	N/A
Primary Use	Web requests via Swoole	CLI commands via Artisan
Request Type	Psr\Http\Message\ServerRequestInterface	Symfony\Component\Console\Input\InputInterface

Sources: src/Http/Kernel.php28-165 src/Console/Kernel.php32-438

HTTP Kernel Request Lifecycle

Sources: src/Http/Kernel.php49-102 src/Http/Kernel.php157-164

The HTTP Kernel extends Hyperf\HttpServer\Server and overrides the onRequest() method (src/Http/Kernel.php49-102) to implement the complete HTTP request lifecycle, including middleware dispatching and exception handling.

Console Kernel Command Execution

Sources: src/Console/Kernel.php95-98 src/Console/Kernel.php103-120 src/Console/Kernel.php402-417 src/Console/Kernel.php434-437

The Console Kernel creates a Hypervel\Console\Application instance (src/Console/Kernel.php408) that wraps Symfony Console, providing command discovery from multiple sources: annotation-based registration, explicit registration, and path-based discovery (src/Console/Kernel.php149-192).

Kernel Initialization

Both kernels are registered in the Application container with specific aliases:

Sources: src/Application.php558

---

Core Design Patterns

Hypervel Foundation implements several key design patterns that form its architectural foundation.

Dependency Injection and Service Container

The Application class extends Hypervel\Container\Container (which wraps Hyperf\Di\Container) and serves as the central service container.

Sources: src/Application.php25 src/Contracts/Application.php13

The container provides three primary binding methods inherited from Hypervel\Container\Container:

• bind(): Register a service with lazy instantiation
• singleton(): Register a singleton service
• instance(): Register an existing instance (e.g., src/Application.php110)

Service resolution occurs through make(), get(), or resolve(), with automatic dependency injection of constructor parameters via Hyperf\Di\Container's reflection-based resolver.

Service Provider Pattern

Service providers are the primary mechanism for organizing service registration and bootstrapping logic. Each provider extends Hypervel\Support\ServiceProvider and implements register() and optionally boot() methods.

Sources: src/Bootstrap/RegisterProviders.php19-53 src/Application.php311-344 src/Application.php398-416 src/Bootstrap/BootProviders.php14-28

The RegisterProviders bootstrapper (src/Bootstrap/RegisterProviders.php14-68) ensures FoundationServiceProvider is registered first (src/Bootstrap/RegisterProviders.php45-49), guaranteeing core framework services (configuration overrides, enhanced dumpers, middleware management) are available before application-specific providers. The FormRequestServiceProvider (src/Providers/FormRequestServiceProvider.php11-23) registers automatic validation for form requests that implement ValidatesWhenResolved.

Facade Pattern

Facades provide static-style access to services in the container. The Hypervel\Support\Facades\Facade base class resolves the underlying service on-demand using PHP's __callStatic() magic method.

Sources: src/Bootstrap/RegisterFacades.php19-35

Facades are registered during bootstrap via Bootstrap\RegisterFacades (src/Bootstrap/RegisterFacades.php14-47), which:

1. Loads facade aliases from composer.json extra.hypervel.aliases (src/Bootstrap/RegisterFacades.php23-27)
2. Loads additional aliases from config/app.php aliases array (src/Bootstrap/RegisterFacades.php29-32)
3. Calls class_alias() for each mapping (src/Bootstrap/RegisterFacades.php33)

This enables both \Hypervel\Support\Facades\Config::get() and the aliased \Config::get() to work identically.

---

Application Container as Central Component

The Application class is the framework's orchestrator, managing the entire application lifecycle.

Core Container Responsibilities

Sources: src/Application.php82-112 src/Application.php546-664

Core Container Aliases

The application registers extensive container aliases via registerCoreContainerAliases() (src/Application.php546-664) to support both Hyperf and Laravel naming conventions:

Abstract Type	Aliases	Line Reference
Psr\Container\ContainerInterface	app, Hyperf\Di\Container, Hyperf\Contract\ContainerInterface, Hypervel\Container\Contracts\Container, Hypervel\Container\Container, Hypervel\Foundation\Contracts\Application, Hypervel\Foundation\Application	549-557
Hypervel\Foundation\Console\Contracts\Kernel	artisan	558
Hyperf\Contract\ConfigInterface	config, Hypervel\Config\Contracts\Repository	559-562
Psr\EventDispatcher\EventDispatcherInterface	events, Hypervel\Event\Contracts\Dispatcher	563-566
Hyperf\HttpServer\Router\DispatcherFactory	router	567
Psr\Log\LoggerInterface	log, Hypervel\Log\LogManager	568-571
Psr\Http\Message\ServerRequestInterface	request, Hyperf\HttpServer\Contract\RequestInterface, Hyperf\HttpServer\Request, Hypervel\Http\Contracts\RequestContract	597-602
Hypervel\Http\Contracts\ResponseContract	response, Hyperf\HttpServer\Contract\ResponseInterface, Hyperf\HttpServer\Response	603-607

This dual-aliasing strategy enables code to use either Hyperf-style or Laravel-style naming. For example, both $app->make('config') and $app->make(\Hyperf\Contract\ConfigInterface::class) resolve to the same service instance.

Sources: src/Application.php546-664

Path Resolution Methods

The Application provides standardized path resolution for common directories through dedicated methods:

Method	Returns	Default Path	Line Reference
basePath($path)	Base installation path	BASE_PATH constant	178-181
path($path)	Application directory	{base}/app	170-173
configPath($path)	Configuration files	{base}/config	186-189
databasePath($path)	Database files	{base}/database	194-197
langPath($path)	Language files	{base}/lang	202-205
publicPath($path)	Public assets	{base}/public	210-213
resourcePath($path)	Resources	{base}/resources	218-221
viewPath($path)	View templates	config('view.config.view_path') or {base}/resources/views	228-236
storagePath($path)	Storage files	{base}/storage	241-244

All paths use joinPaths() (src/Application.php249-252) which delegates to Hypervel\Filesystem\join_paths() for cross-platform path normalization.

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

---

Bootstrap and Initialization

The application follows a strict bootstrap sequence to ensure proper initialization order.

Bootstrap Sequence

Sources: src/Application.php82-90 src/Application.php118-129 src/Bootstrap/RegisterFacades.php19-35 src/Bootstrap/RegisterProviders.php19-53 src/Bootstrap/BootProviders.php19-28 src/Application.php398-416

Provider Registration Priority

The RegisterProviders bootstrapper implements a critical architectural decision: FoundationServiceProvider must be registered before all other providers.

Sources: src/Bootstrap/RegisterProviders.php44-49

This ensures core framework services (configuration overrides, enhanced VarDumper via VarDumperServiceProvider, middleware management, and form request validation) are available before application providers boot. The code explicitly searches for FoundationServiceProvider::class in the discovered providers array and moves it to the front using array_unshift() (src/Bootstrap/RegisterProviders.php45-49).

---

Integration with Hyperf

Hypervel Foundation integrates with Hyperf through the ConfigProvider class, which implements Hyperf's component discovery protocol.

ConfigProvider Structure

The ConfigProvider (src/ConfigProvider.php18-47) returns configuration arrays that Hyperf's component discovery system consumes:

Sources: src/ConfigProvider.php20-46

Dependency Override Strategy

The ConfigProvider overrides specific Hyperf dependencies to inject Hypervel's enhanced implementations:

Hyperf Interface	Hypervel Implementation	Purpose	Line Reference
Hyperf\Contract\ApplicationInterface	Console\ApplicationFactory	Enhanced Artisan console application with Laravel-style command API	24
Hyperf\Framework\Event\Listener\InitProcessTitleListener	Listeners\SetProcessTitle	Sets process title from config('app.name') instead of default	25

Sources: src/ConfigProvider.php23-26 src/Listeners/SetProcessTitle.php11-18 src/Console/ApplicationFactory.php11-22

The ApplicationFactory creates a Hypervel\Console\Application instance that wraps Symfony Console with Laravel-compatible command signatures and helper methods.

Event-Driven Configuration Reloading

The framework registers two event listeners for lifecycle management:

Listener	Event	Purpose	Line Reference
Exceptions\ErrorExceptionHandler	N/A (exception handler)	Converts PHP errors to exceptions	28
Listeners\ReloadDotenvAndConfig	N/A (boot listener)	Hot-reloads .env and config files during development	29

The ReloadDotenvAndConfig listener enables configuration changes without server restart, crucial for Swoole's long-running process model.

Sources: src/ConfigProvider.php27-30 src/Listeners/ReloadDotenvAndConfig.php11-31

---

Key Architectural Decisions

1. Container Inheritance

Application extends Container rather than composing it, enabling direct use as both application instance and DI container:

This design allows both array access ($app['config']) and method calls ($app->make('config')) for service resolution. The inheritance from Hypervel\Container\Container (which wraps Hyperf\Di\Container) ensures seamless integration with Hyperf's dependency injection system while providing a Laravel-compatible API surface.

Sources: src/Application.php25

2. Macroable Application

The Application uses the Macroable trait (src/Application.php27), allowing runtime extension of the application instance with custom methods—a Laravel pattern for framework extensibility.

Sources: src/Application.php27

3. Environment Delegation

Environment detection delegates to a dedicated Hypervel\Support\Environment service (src/Application.php259-306) rather than implementing directly:

This follows the single-responsibility principle and enables easier testing by centralizing environment logic in a dedicated service. Methods like isLocal(), isProduction(), runningUnitTests(), and hasDebugModeEnabled() all delegate to the Environment service.

Sources: src/Application.php259-306

4. Strict Bootstrap Order

The framework enforces strict bootstrap ordering through bootstrapWith() (src/Application.php118-129), dispatching events before and after each bootstrapper:

• bootstrapping: ClassName
• bootstrapped: ClassName

This enables precise lifecycle hooks for debugging and extension.

Sources: src/Application.php118-129 src/Application.php134-145

5. Service Provider Lifecycle Separation

Service providers separate registration (register()) from booting (boot()), ensuring all services are registered before any provider boots—preventing order-dependent bugs:

The Application::boot() method (src/Application.php398-416) implements a two-phase boot process:

1. Fire "booting" callbacks (src/Application.php407)
2. Boot each registered provider (src/Application.php409-411)
3. Mark as booted and fire "booted" callbacks (src/Application.php413-415)

This guarantees that when a provider's boot() method runs, all other providers have already executed their register() methods, making all services available for dependency injection.

Sources: src/Application.php311-344 src/Application.php398-416 src/Application.php421-430

6. Base Path Immutability

The base path is set once during construction (src/Application.php84) and stored with normalized slashes (src/Application.php162), ensuring consistent path resolution throughout the application lifecycle.

Sources: src/Application.php82-90 src/Application.php160-165

---

Design Pattern Summary

Pattern	Implementation	Purpose	Code Reference
Dependency Injection	Application extends Container	Automatic dependency resolution, testability	src/Application.php25
Service Provider	ServiceProvider with register/boot lifecycle	Organized service registration and configuration	src/Application.php311-344
Facade	Static proxies via Facade::__callStatic()	Convenient static API while maintaining testability	src/Bootstrap/RegisterFacades.php19-35
Template Method	bootstrapWith() with ordered bootstrappers	Controlled initialization sequence with event hooks	src/Application.php118-129
Registry	Container aliases via registerCoreContainerAliases()	Unified service access across naming conventions	src/Application.php546-664
Observer	Booting/booted callbacks via $bootingCallbacks	Lifecycle hooks for extensions	src/Application.php435-450
Strategy	Replaceable DefinitionSourceInterface	Custom DI configuration strategies	src/Application.php92-95
Dual Kernel	Separate Http\Kernel and Console\Kernel	Request-type-specific processing pipelines	src/Http/Kernel.php28 src/Console/Kernel.php32

Sources: src/Application.php25-688 src/Bootstrap/RegisterProviders.php14-68 src/Bootstrap/RegisterFacades.php14-47 src/Http/Kernel.php28-165 src/Console/Kernel.php32-438

---

This architecture provides Laravel developers a familiar development experience while leveraging Hyperf's performance advantages, maintaining clear separation of concerns through layering and design patterns.