Hyperf Integration and Swoole Foundation

This document explains how Hypervel integrates with the Hyperf framework and leverages Swoole's coroutine capabilities. It covers the dual-provider architecture that combines Hyperf's ConfigProvider pattern with Laravel-style ServiceProvider classes, and describes coroutine safety considerations when building applications on this foundation.

For information about the application lifecycle and bootstrapping process, see Application Container and Lifecycle. For details about service provider registration, see Service Providers and Bootstrapping.

---

Architecture Overview

Hypervel builds on Hyperf, leveraging Swoole's coroutine runtime while providing Laravel-compatible APIs. The framework operates through a layered architecture where each Hypervel component provides both a ConfigProvider (Hyperf integration) and optional ServiceProvider (application-level registration).

Framework Stack and Component Integration

Sources: src/foundation/src/Application.php25-90 composer.json238-279 composer.json99-145

---

Container and Dependency Injection

Hypervel's Application class extends a custom Container implementation that wraps Hyperf's dependency injection container. This provides Laravel-compatible container methods while utilizing Hyperf's powerful DI capabilities.

Container Hierarchy and Initialization

The Application constructor at src/foundation/src/Application.php82-90 receives a base path and initializes the DI container through DefinitionSourceFactory:

Sources: src/foundation/src/Application.php82-95 src/container/composer.json22-26 composer.json238-270

Service Resolution and Aliasing

The Application registers extensive container aliases mapping PSR interfaces and Hyperf classes to Hypervel implementations. This enables developers to resolve services using multiple interface names:

Primary Interface	Aliases	Implementation
Psr\Container\ContainerInterface	app, Hyperf\Di\Container, Hypervel\Container\Container, Hypervel\Foundation\Application	Application singleton
Hyperf\Contract\ConfigInterface	config, Hypervel\Config\Contracts\Repository	Configuration repository
Psr\EventDispatcher\EventDispatcherInterface	events, Hypervel\Event\Contracts\Dispatcher	Event dispatcher
Psr\Http\Message\ServerRequestInterface	request, Hyperf\HttpServer\Request, Hypervel\Http\Contracts\RequestContract	Current request

Sources: src/foundation/src/Application.php546-664

---

The Dual-Provider System

Hypervel implements a dual-provider architecture that combines two registration patterns:

1. ConfigProviders - Hyperf's native service registration mechanism
2. ServiceProviders - Laravel-style service providers for application-level concerns

ConfigProvider Registration Flow

ConfigProviders are discovered from composer.json238-270:

Sources: composer.json238-270 src/foundation/composer.json60-67

ConfigProvider Structure

Each Hypervel component package includes a ConfigProvider class that returns configuration arrays:

Sources: src/foundation/composer.json60-67 src/router/composer.json46-49 src/cache/composer.json45-52

ServiceProvider Registration Flow

ServiceProviders are discovered from composer.json271-279:

The registration logic at src/foundation/src/Application.php309-345 follows a two-phase lifecycle with register() and boot() methods.

Sources: composer.json271-279 src/foundation/src/Application.php309-345 src/foundation/src/Application.php398-430

Integration Points

Concern	ConfigProvider	ServiceProvider
Registration Phase	Application construction	Bootstrap phase
Purpose	Framework-level service registration	Application-level logic and bindings
Discovery	extra.hyperf.config in composer.json	extra.hypervel.providers in composer.json
Lifecycle	Loaded once at container build	Registered during bootstrap, booted after
DI Integration	Direct definitions in container	Uses container after construction
Examples	CacheManager, Router, EventDispatcher	NotificationServiceProvider, ViewServiceProvider

Sources: src/foundation/composer.json60-72 src/notifications/composer.json50-54 src/view/composer.json

---

Swoole Coroutine Foundation

Swoole provides a coroutine-based concurrency model that allows thousands of concurrent connections without traditional threading overhead. Hypervel builds on this foundation while maintaining Laravel-compatible APIs.

Coroutine Execution Model

Each worker process runs a Swoole event loop that spawns coroutines for incoming requests. The Hyperf\Context\Context class provides coroutine-local storage keyed by coroutine ID, ensuring each request's data remains isolated.

Sources: composer.json119-122 src/http/src/Request.php971-984

Context Isolation Pattern

Hyperf's Context class provides coroutine-local storage, preventing data leakage between concurrent requests in the same worker process. The Request class demonstrates proper usage.

Key Context Keys Used:

Context Key	Purpose	Set/Accessed At
ServerRequestInterface::class	Stores PSR-7 request	src/http/src/Request.php974
'http.request.parsedData'	Cached parsed data	src/http/src/Request.php339-340
HyperfRequest::class . '.properties.requestUri'	Cached request URI	HyperfRequest parent
HyperfRequest::class . '.properties.pathInfo'	Cached path info	HyperfRequest parent

Sources: src/http/src/Request.php971-984 src/http/src/Request.php334-358 tests/Http/RequestTest.php36-43

Request Context Retrieval with Error Handling

The Request::getRequest() method at src/http/src/Request.php971-984 demonstrates coroutine-safe context retrieval with proper error handling:

This pattern ensures that:

1. The request is always retrieved from the current coroutine's context
2. Missing context is caught with a descriptive error message
3. Other TypeError exceptions are properly propagated

The merge() method at src/http/src/Request.php334-343 shows how to update context safely:

Sources: src/http/src/Request.php971-984 src/http/src/Request.php334-358

---

HTTP Layer Integration

Hypervel's HTTP layer extends Hyperf's HTTP server components while providing Laravel-compatible APIs.

Request Extension Pattern

The Request class adds Laravel-style convenience methods while maintaining PSR-7 compatibility:

Sources: src/http/src/Request.php31-48 src/http/src/Contracts/RequestContract.php18-442

Request Method Extensions

Method Category	Examples	Purpose
Type Casting	boolean(), integer(), float(), enum()	Type-safe input retrieval
Collections	collect(), only(), except()	Fluent data manipulation
Validation	filled(), anyFilled(), whenFilled()	Input presence checking
Routing	route(), routeIs(), fullUrlIs()	Route information access
Content Negotiation	wantsJson(), expectsJson(), accepts()	Response type determination

Sources: src/http/src/Request.php74-196 src/http/src/Request.php446-547 src/http/src/Request.php694-735

---

Coroutine Safety Considerations

When building applications on Hypervel, developers must be aware of coroutine-specific patterns and potential pitfalls.

Coroutine Safety Patterns

Safe Patterns:

Pattern	Implementation	Example Location
Context storage	Context::set() / Context::get()	src/http/src/Request.php974
Context override	Context::override() with closure	src/http/src/Request.php338-341
Container resolution	ApplicationContext::getContainer()->get()	src/http/src/Request.php871-872
Immutable data	Value objects passed by value	Throughout framework

Unsafe Patterns:

Pattern	Why Unsafe	Impact
Global variables	Shared across coroutines	Data leakage between requests
Static properties	Worker-level singleton	State persists across requests
Thread-local assumptions	PHP doesn't have thread-local	Coroutines != threads
Mutable singletons	State shared in worker	Race conditions

Sources: src/http/src/Request.php338-341 src/http/src/Request.php871-882 src/http/src/Request.php971-984

Context-Aware Request Resolution

The framework provides multiple ways to access the current request, all resolving through the coroutine-local context:

The Request class resolves its data from context at src/http/src/Request.php971-984:

The facade accessor is defined at src/support/src/Facades/Request.php146-150:

Sources: src/support/src/Facades/Request.php144-150 src/http/src/Request.php971-984 src/foundation/src/Application.php597-602

---

Performance Considerations

Swoole's coroutine model provides significant performance advantages over traditional PHP execution:

Concurrency Model Comparison

Aspect	Traditional PHP-FPM	Swoole Coroutines
Process Model	Process per request	Shared worker processes
Concurrency	Limited by process count	Thousands per worker
Memory	High (process overhead)	Low (shared memory)
Startup Cost	Bootstrap per request	Bootstrap once per worker
I/O Handling	Blocking	Non-blocking async
State Isolation	Process isolation	Coroutine context isolation

Worker Process Architecture

Hyperf's server configuration determines worker process count and lifecycle:

Each worker process:

• Bootstraps the application once at startup
• Maintains the container and service registrations
• Handles thousands of concurrent coroutines
• Isolates state using context managers

Sources: composer.json120-122 composer.json42

---

Package Dependencies

Hypervel's dependency structure shows the integration layers:

Core Hyperf Dependencies

Package	Version	Purpose
hyperf/framework	~3.1.0	Core framework foundation
hyperf/di	~3.1.0	Dependency injection container
hyperf/http-server	~3.1.0	HTTP server implementation
hyperf/config	~3.1.0	Configuration management
hyperf/dispatcher	~3.1.0	Middleware dispatcher
hyperf/engine	^2.10	Swoole engine abstraction
hyperf/context	~3.1.0	Coroutine context management

Hypervel Layer Dependencies

Package	Purpose
hypervel/container	Container extensions and contracts
hypervel/support	Helper functions and utilities
hypervel/http	HTTP layer extensions
hypervel/router	Routing and URL generation
hypervel/cache	Caching with Swoole support

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

---

Summary

Hypervel's integration with Hyperf and Swoole provides:

1. Laravel-Compatible APIs - Familiar interfaces and patterns for Laravel developers
2. High Performance - Swoole's coroutine-based concurrency for thousands of concurrent requests
3. Dual-Provider System - Combining Hyperf's ConfigProviders with Laravel's ServiceProviders
4. Coroutine Safety - Context-based isolation preventing state leakage between requests
5. PSR Standards - Full PSR-7, PSR-11, and PSR-14 compliance
6. Extensibility - Modular package architecture with 33+ replaceable components

The framework achieves compatibility and performance by carefully layering Laravel-style APIs over Hyperf's coroutine-safe infrastructure, using context managers to maintain request isolation while enabling massive concurrency within shared worker processes.

Sources: src/foundation/src/Application.php composer.json src/http/src/Request.php src/container/composer.json