Installation and Configuration

This document covers the installation process, system requirements, and initial configuration for the hypervel/event package. It explains how to install the package via Composer, understand its dependencies, and configure the dependency injection container for proper event system operation.

For information about using the event system after installation, see Basic Concepts. For advanced configuration options related to queuing and broadcasting, see Configuring Queued Events and Event Broadcasting.

System Requirements

The hypervel/event package has specific system requirements that must be met before installation:

Component	Requirement	Purpose
PHP	^8.2	Minimum PHP version for modern language features
Hyperf Framework	~3.1.0	Core framework integration
Operating System	Linux/macOS recommended	Swoole compatibility

Core Dependencies

The package requires several Hyperf framework components and external libraries. Each dependency serves a specific purpose in the event system:

Dependency	Version	Purpose
hyperf/event	~3.1.0	Base event system, PSR-14 interfaces
hyperf/collection	~3.1.0	Collection utilities for listener management
hyperf/context	~3.1.0	Context management for deferred events
hyperf/stringable	~3.1.0	String utilities for event name matching
hypervel/bus	~0.1	Command bus integration for queued listeners
laravel/serializable-closure	^1.3	Serialization for closure-based listeners

Optional Dependencies:

Dependency	Version	Purpose
hypervel/queue	~0.1.0	Required for ShouldQueue listeners and CallQueuedListener

Package Dependency Structure

Sources: composer.json32-43

Installation Process

Step 1: Install via Composer

Install the package using Composer in your Hyperf application:

Step 2: Install Optional Dependencies

For asynchronous event processing, install the queue component:

Step 3: Verify Autoloading Configuration

The package automatically configures PSR-4 autoloading and includes function files. The dual namespace strategy provides both native Hypervel APIs and Laravel compatibility:

Autoload Type	Namespace/Path	Purpose
PSR-4	Hypervel\Event\ → src/	Native implementation (PSR-14 compliant)
PSR-4	Illuminate\Events\ → illuminate/	Laravel-compatible aliases and classes
Files	src/Functions.php	Global helpers: event(), queueable()

Dual Namespace Strategy:

The package provides two namespaces to support code migration and compatibility:

• Hypervel\Event\: Native PSR-14-compliant classes (EventDispatcher, ListenerProvider, QueuedClosure)
• Illuminate\Events\: Laravel-style classes for compatibility (CallQueuedListener, Dispatcher aliases)

This allows developers to use Laravel event patterns while benefiting from Hyperf's coroutine-based performance.

Sources: composer.json23-31

Configuration Setup

Dependency Injection Registration

The package automatically registers its services with the Hyperf container through the ConfigProvider class:

Service Registration in ConfigProvider

The ConfigProvider registers two PSR interfaces with their factory implementations:

Interface	Factory	Created Class	Key Dependencies
EventDispatcherInterface	EventDispatcherFactory	EventDispatcher	ListenerProviderInterface, StdoutLoggerInterface, ContainerInterface
ListenerProviderInterface	ListenerProviderFactory	ListenerProvider	Configuration array, AnnotationCollector

EventDispatcherFactory Initialization:

The EventDispatcherFactory performs the following setup:

1. Resolves ListenerProviderInterface from container
2. Resolves StdoutLoggerInterface for logging
3. Creates EventDispatcher instance with these dependencies
4. Sets up queue resolver: setQueueResolver(fn () => $container->get(QueueFactoryContract::class))

This lazy queue resolver ensures the queue system is only instantiated when needed (e.g., when a ShouldQueue listener is encountered).

Sources: src/ConfigProvider.php14-19 src/EventDispatcherFactory.php14-23

Hyperf Framework Integration

The package integrates with Hyperf through the configuration provider mechanism defined in composer.json:

Framework Integration Mechanism

The integration happens automatically through Hyperf's package discovery:

1. Package Discovery: Hyperf reads composer.json extra configuration
2. Config Provider Loading: Loads Hypervel\Event\ConfigProvider class
3. Service Registration: ConfigProvider::__invoke() returns dependency mappings
4. Container Setup: Hyperf registers factories in the DI container
5. Function Loading: Composer autoloads src/Functions.php for global helpers

Configuration Entry Point:

The extra.hyperf.config section in composer.json specifies the entry point:

Sources: composer.json47-50 src/ConfigProvider.php10-21

Configuration Files

Listener Configuration

Create a config/autoload/listeners.php file to register event listeners via configuration:

The ListenerProviderFactory reads this configuration file during initialization to register listeners. See Creating Event Listeners for detailed registration methods.

Optional: Queue Configuration

If using hypervel/queue for asynchronous event processing, ensure queue configuration is present. The EventDispatcherFactory sets up a queue resolver that lazily loads the queue factory when needed:

• Queue resolver: fn () => $container->get(QueueFactoryContract::class)
• This resolver is called only when dispatching queued listeners
• If hypervel/queue is not installed, queued listeners will fail with a container resolution error

See Configuring Queued Events for queue-specific configuration.

Sources: src/EventDispatcherFactory.php20

Verification and Testing

Verify Installation

After installation, verify the package is properly configured by checking service resolution:

Method 1: Container Resolution

Method 2: Dependency Injection

Method 3: Global Functions

Verification Checklist

Component	Verification Method	Expected Result
EventDispatcherInterface	Container resolution	Hypervel\Event\EventDispatcher instance
ListenerProviderInterface	Container resolution	Hypervel\Event\ListenerProvider instance
event() function	Direct call	Function executes without error
queueable() function	Direct call	Returns QueuedClosure instance
Dual namespaces	Class lookup	Both Hypervel\Event\* and Illuminate\Events\* classes available

Sources: src/ConfigProvider.php15-17 composer.json28-30

Next Steps

After successful installation and configuration:

1. Learn Basic Concepts: See Basic Concepts for fundamental event system usage
2. Create Listeners: See Creating Event Listeners for listener registration
3. Configure Queuing: See Configuring Queued Events for async processing setup
4. Explore Advanced Features: See Advanced Usage for broadcasting and wildcards

The installation provides a fully functional event system with PSR-14 compliance, Laravel compatibility, and integration with the Hypervel ecosystem.