Overview

Purpose and Scope

The hypervel/event package is a PSR-14 compatible event system built on Hyperf with Laravel-style APIs. It provides event dispatching, listener management, asynchronous processing via queues, transaction-aware event handling, and real-time broadcasting capabilities.

This page introduces the package architecture, key components, and processing patterns. See page 1.1 for installation, page 1.2 for basic concepts, and page 2 for core system details.

Sources: composer.json1-55 src/EventDispatcher.php1-618

What is hypervel/event

The hypervel/event package implements PSR-14 EventDispatcherInterface and ListenerProviderInterface while providing Laravel-compatible APIs. It runs on Hyperf 3.1's coroutine-based runtime (Swoole) and integrates with the Hypervel ecosystem (hypervel/bus, hypervel/queue).

The package provides dual namespace support: Hypervel\Event for native implementation and Illuminate\Events for Laravel compatibility. It extends hyperf/event with features like SerializableClosure for queueable closures, transaction-aware dispatching, and broadcasting.

Sources: composer.json24-43 src/EventDispatcher.php31-57

Key Features

Feature	Implementation	Key Code Symbols
PSR-14 Compliance	Implements EventDispatcherInterface and ListenerProviderInterface	EventDispatcher, ListenerProvider
Listener Management	Priority-based registry with wildcard matching (* patterns)	ListenerProvider, ListenerData, SplPriorityQueue
Queue Integration	Async execution via CallQueuedListener jobs	QueuedClosure, CallQueuedListener, InvokeQueuedClosure
Transaction Awareness	Event/listener deferral until DB commit	ShouldDispatchAfterCommit, ShouldHandleEventsAfterCommit, TransactionManager
Closure Serialization	Queue closures using Laravel SerializableClosure	QueuedClosure, laravel/serializable-closure
Broadcasting	Real-time event streaming to WebSocket clients	ShouldBroadcast, BroadcastFactory
Context-Based Deferral	Programmatic event batching via defer()	EventDispatcher::defer(), Context
Dual Namespace	Laravel and Hypervel compatibility layers	Hypervel\Event\*, Illuminate\Events\*

Sources: composer.json24-43 src/EventDispatcher.php31-618

System Architecture

Component Dependency Graph

Architecture Overview: The EventDispatcher class implements the PSR-14 EventDispatcherInterface and coordinates with ListenerProvider for listener retrieval. Factories handle dependency injection via ConfigProvider. The system provides both src/ and illuminate/ implementations of CallQueuedListener for framework compatibility.

Sources: composer.json24-43 src/EventDispatcher.php31-57

Class Relationships and Method Interactions

Method Call Patterns: When EventDispatcher::dispatch() is called, it checks for deferral (shouldDeferEvent()) and transaction awareness (ShouldDispatchAfterCommit), then invokes invokeListeners() which calls ListenerProvider::getListenersForEvent(). For queued listeners, createQueuedHandlerCallable() creates a CallQueuedListener job via queueHandler().

Sources: src/EventDispatcher.php49-618

Event Dispatch Flow with Code Paths

Key Decision Points:

• Line 64-73: shouldDeferEvent() checks Context::get('__event.deferring') to batch events
• Line 78-85: ShouldDispatchAfterCommit interface defers entire event dispatch
• Line 273-274: handlerShouldBeQueued() checks ShouldQueue interface on listener class
• Line 287-292: handlerShouldBeDispatchedAfterDatabaseTransactions() checks ShouldHandleEventsAfterCommit or $listener->afterCommit property

Sources: src/EventDispatcher.php62-88 src/EventDispatcher.php157-174 src/EventDispatcher.php273-282 src/EventDispatcher.php459-478

Namespace and Dependency Structure

Dual Namespace Strategy: The package exposes Hypervel\Event for native usage and Illuminate\Events for Laravel compatibility. The src/ directory contains the primary implementation while illuminate/ provides Laravel-compatible wrappers. Both namespaces are registered via PSR-4 autoloading in composer.json:24-27.

Sources: composer.json23-43

Core Components

Event Dispatch and Management

Class	File	Key Methods	Implements/Extends
EventDispatcher	src/EventDispatcher.php	dispatch(), listen(), until(), defer(), subscribe()	Contracts\Dispatcher (PSR-14)
ListenerProvider	src/ListenerProvider.php	on(), getListenersForEvent(), has(), forget()	Contracts\ListenerProvider (PSR-14)
ListenerData	src/ListenerData.php	__construct($event, $listener, $priority)	Value object

Queue Integration

Class	File	Key Methods	Purpose
QueuedClosure	src/QueuedClosure.php	catch(), onConnection(), onQueue(), delay(), resolve()	Wraps closures with Laravel SerializableClosure for queueing
CallQueuedListener	src/CallQueuedListener.php	handle(Container), properties: $tries, $timeout, $afterCommit	Job wrapper for queued listener execution
CallQueuedListener	illuminate/CallQueuedListener.php	handle(Container)	Laravel-compatible version
InvokeQueuedClosure	src/InvokeQueuedClosure.php	handle(Closure)	Executes deserialized closures in queue worker

Contracts (Interfaces)

Interface	File	Purpose
Dispatcher	src/Contracts/Dispatcher.php	PSR-14 EventDispatcherInterface extension
ListenerProvider	src/Contracts/ListenerProvider.php	PSR-14 ListenerProviderInterface extension
ShouldQueue	src/Contracts/ShouldQueue.php	Marker interface for queued listeners
ShouldDispatchAfterCommit	src/Contracts/ShouldDispatchAfterCommit.php	Event-level transaction deferral
ShouldHandleEventsAfterCommit	src/Contracts/ShouldHandleEventsAfterCommit.php	Listener-level transaction deferral

Factory and Configuration

Class	File	Key Methods	Purpose
ConfigProvider	src/ConfigProvider.php	__invoke()	Hyperf dependency injection configuration
EventDispatcherFactory	src/EventDispatcherFactory.php	__invoke(ContainerInterface)	Creates EventDispatcher with dependencies
ListenerProviderFactory	src/ListenerProviderFactory.php	__invoke(ContainerInterface)	Creates ListenerProvider with registered listeners

Helper Functions

Function	File	Signature	Purpose
event()	src/Functions.php	event($event = null, $payload = [])	Dispatches events or returns dispatcher instance
queueable()	src/Functions.php	queueable(Closure $closure)	Wraps closure in QueuedClosure

Sources: src/EventDispatcher.php31-618 composer.json24-30

Event Processing Patterns

Synchronous Execution

Default behavior. EventDispatcher::dispatch() immediately calls invokeListeners(), which iterates through listeners from ListenerProvider::getListenersForEvent() in priority order. Execution is synchronous unless listener implements ShouldQueue.

Sources: src/EventDispatcher.php157-174

Asynchronous Queue Processing

Listeners implementing ShouldQueue are wrapped in CallQueuedListener jobs via createQueuedHandlerCallable() and queueHandler(). The job is pushed to the queue system and later executed by queue workers via CallQueuedListener::handle().

Key Code: src/EventDispatcher.php397-408 src/EventDispatcher.php413-424 src/EventDispatcher.php459-478

Sources: src/EventDispatcher.php397-522

Transaction-Aware Deferral

Events implementing ShouldDispatchAfterCommit have their entire dispatch deferred via TransactionManager::addCallback(). Alternatively, individual listeners with ShouldHandleEventsAfterCommit or $afterCommit = true property are deferred at listener level via createCallbackForListenerRunningAfterCommits().

Event-Level: src/EventDispatcher.php78-85
Listener-Level: src/EventDispatcher.php287-292 src/EventDispatcher.php429-440

Sources: src/EventDispatcher.php78-85 src/EventDispatcher.php287-292 src/EventDispatcher.php429-440

Context-Based Deferral

The defer() method batches events by setting Context::set('__event.deferring', true). Events dispatched within the callback are stored in __event.deferred_events context and only dispatched when the callback completes.

Code: src/EventDispatcher.php573-598 src/EventDispatcher.php603-617

Sources: src/EventDispatcher.php573-617

Package Integration

The Hypervel Event package is designed to integrate seamlessly with:

• Hyperf Framework: Core runtime and dependency injection
• Hypervel Ecosystem: Bus messaging (hypervel/bus) and queue processing (hypervel/queue)
• Laravel Components: SerializableClosure for queue compatibility
• PSR Standards: PSR-14 Event Dispatcher and PSR-11 Container interfaces

The package automatically registers itself via the ConfigProvider class and provides global helper functions through autoloaded files.

Sources: composer.json48-50 composer.json28-30