 |
VOOZH | about |
|
VOOZH | about |
This document describes the physical organization of the hypervel/event package, including its dual namespace architecture, dependency requirements, PSR standards compliance, and integration points with external frameworks. This provides the foundation for understanding how the package fits into both Hyperf and Laravel ecosystems.
For information about how the factories wire up these dependencies at runtime, see Factory System and Dependency Injection. For details on the specific interfaces and contracts, see Contracts and Interfaces.
The package implements a dual namespace strategy to provide compatibility with both Hyperf and Laravel codebases. This allows code written for Laravel's event system to work with minimal modifications while providing native Hyperf integration.
Dual Namespace Mapping
Sources: composer.json24-27
The autoloading configuration defines two PSR-4 namespace roots:
| Namespace | Directory | Purpose |
|---|---|---|
Hypervel\Event\ | src/ | Native implementation with Hyperf integration |
Illuminate\Events\ | illuminate/ | Laravel-compatible queue job wrappers |
| Functions | src/Functions.php | Global helper functions (event(), queueable()) |
The Illuminate\Events\ namespace provides compatibility classes that match Laravel's queue system expectations:
Illuminate\Events\CallQueuedListener illuminate/CallQueuedListener.php - Queue job wrapper that Laravel's queue workers recognizeIlluminate\Events\InvokeQueuedClosure illuminate/InvokeQueuedClosure.php - Handles deserialization and execution of queued closuresThis approach allows the package to work seamlessly in both ecosystems without requiring changes to existing Laravel-based event listeners.
Sources: composer.json24-30 src/EventDispatcher.php25
Package Directory Organization
Sources: composer.json24-30
The package requires several Hyperf framework components and integrates with Laravel's closure serialization library.
| Package | Version | Purpose | Used By |
|---|---|---|---|
php | ^8.2 | Modern PHP features (enums, readonly, union types) | All classes |
hyperf/event | ~3.1.0 | Base event interfaces, ListenerProvider parent class | ListenerProvider |
hyperf/collection | ~3.1.0 | Array manipulation utilities (Arr class) | EventDispatcher, ListenerProvider |
hyperf/context | ~3.1.0 | Coroutine-safe context storage | EventDispatcher, deferred events |
hyperf/stringable | ~3.1.0 | String parsing utilities (Str::parseCallback) | EventDispatcher |
hypervel/bus | ~0.1 | Command bus integration | Transaction-aware dispatching |
laravel/serializable-closure | ^1.3 | Serialize closures for queue storage | QueuedClosure, queue integration |
Sources: composer.json32-39
Direct Dependency Usage Mapping
Sources: src/EventDispatcher.php9-12 composer.json32-39
hyperf/collection)Used extensively for array operations. Key usage at src/EventDispatcher.php535 with Arr::wrap() for normalizing listener arrays during subscriber registration.
hyperf/context)Enables coroutine-safe storage for deferred events. Critical for the defer() method implementation at src/EventDispatcher.php573-598 Context keys used:
__event.deferring - Whether currently in defer mode__event.deferred_events - Buffered events waiting for dispatch__event.events_to_defer - Whitelist of events to deferhyperf/stringable)Provides the Str::parseCallback() utility at src/EventDispatcher.php299 to parse class-based listener strings (e.g., "MyListener@handle" → ["MyListener", "handle"]).
laravel/serializable-closure)Required for QueuedClosure to wrap PHP closures for queue storage. Closures are not naturally serializable, so this package uses reflection to extract closure code and context.
Sources: src/EventDispatcher.php9-12 src/EventDispatcher.php299 src/EventDispatcher.php535 src/EventDispatcher.php573-598
The package suggests but does not require hypervel/queue for asynchronous event processing:
Sources: composer.json41-43
When hypervel/queue is not available:
ShouldQueue listeners will still be registered but cannot be queuedQueuedClosure can be instantiated but fails at dispatch timeEventDispatcher::setQueueResolver() src/EventDispatcher.php369-374Queue Dependency Resolution
Sources: src/EventDispatcher.php20-23 src/EventDispatcher.php359-362 src/EventDispatcher.php397-408
The queue factory is resolved lazily through a callback set by EventDispatcherFactory:
The package extends and implements multiple PSR (PHP Standards Recommendations) interfaces to ensure interoperability.
PSR Standards Integration
Sources: src/EventDispatcher.php27-28 src/EventDispatcher.php31
The core interfaces extend PSR-14 to ensure compatibility with any PSR-14 compliant system:
EventDispatcherInterface: Defines dispatch(object $event) contractListenerProviderInterface: Defines getListenersForEvent(object $event): iterableStoppableEventInterface: Checked at src/EventDispatcher.php168 to halt propagationUsed for dependency resolution at multiple points:
The container is optional and falls back to ApplicationContext::getContainer() if not provided.
Optional logging support at src/EventDispatcher.php93-111:
When a LoggerInterface implementation is provided, the dispatcher logs each listener execution.
Sources: src/EventDispatcher.php27-28 src/EventDispatcher.php49-57 src/EventDispatcher.php93-111 src/EventDispatcher.php168
The composer autoload configuration enables both PSR-4 class loading and function file inclusion.
Autoload Configuration Flow
Sources: composer.json23-31
The package includes a functions file with global helpers:
This file is loaded on every request, providing the event() and queueable() helper functions that facade the event dispatcher. These functions are documented in Helper Functions.
Sources: composer.json28-30
The package integrates with multiple frameworks through specific extension points and configuration mechanisms.
Hyperf Integration Architecture
Sources: composer.json48-50
The ConfigProvider class is automatically discovered through Hyperf's package scanning:
This hooks into Hyperf's dependency injection system to register factories and discover listener annotations. The full factory system is covered in Factory System and Dependency Injection.
While built on Hyperf, the package maintains Laravel API compatibility through:
illuminate/ directorylisten(), dispatch(), until())CallQueuedListener matching Laravel's expectationsThis dual compatibility allows:
Sources: composer.json24-27 composer.json39
The package integrates with Hypervel\Database\TransactionManager (from hypervel/bus) for transaction-aware event dispatching:
The transaction manager is optional; if not available, transaction-aware features gracefully degrade to immediate dispatch.
Integration with Hypervel\Broadcasting\Contracts\Factory enables real-time event broadcasting:
Events implementing ShouldBroadcast are automatically queued to broadcasting channels. See Event Broadcasting for details.
Sources: src/EventDispatcher.php13-15 src/EventDispatcher.php78-85 src/EventDispatcher.php197-200 src/EventDispatcher.php379-382
The package uses lazy resolver callbacks for optional dependencies to avoid hard coupling:
Lazy Dependency Resolution Pattern
Sources: src/EventDispatcher.php36-47 src/EventDispatcher.php359-392
The queue factory is resolved through a callback:
This allows the queue to be unavailable at construction time and resolved only when needed for queued listeners.
Similarly, the transaction manager uses lazy resolution:
Returns null if no transaction manager is available, allowing graceful degradation.
Sources: src/EventDispatcher.php36-47 src/EventDispatcher.php359-392
All Hyperf dependencies target version ~3.1.0, ensuring compatibility with Hyperf 3.1.x releases:
This constraint allows patch and minor version updates within 3.1.x while preventing breaking changes from 3.2.x.
Requires PHP ^8.2 to leverage modern language features:
object|string)The package uses semantic versioning with branch alias:
The 0.3-dev alias indicates pre-1.0 development status. Breaking changes may occur between minor versions (0.x releases).
Sources: composer.json32-39 composer.json51-53
The hypervel/event package employs a sophisticated structure that bridges multiple ecosystems:
| Aspect | Implementation |
|---|---|
| Namespace Strategy | Dual: Hypervel\Event\ (native) + Illuminate\Events\ (compatibility) |
| Core Framework | Hyperf 3.1.x with PSR-14 compliance |
| Optional Features | Queue via hypervel/queue, transactions via hypervel/bus |
| Laravel Integration | Through laravel/serializable-closure and compatible job format |
| PHP Version | 8.2+ for modern language features |
| Dependency Resolution | Lazy resolver pattern for optional services |
This architecture enables the package to serve as a high-performance event system for Hyperf applications while maintaining API familiarity for Laravel developers and providing optional integrations with queue and transaction systems.
Refresh this wiki