README

A PSR-14 Event Dispatcher library for Mezzio/Laminas applications, providing seamless integration between League Event and Laminas ServiceManager.

Features

• ✅ PSR-14 Compliant - Full PSR-14 Event Dispatcher implementation
• ✅ Laminas Integration - Native ServiceManager/Dependency Injection support
• ✅ Configuration-Based - Register listeners and subscribers via configuration arrays
• ✅ Immutable Events - Type-safe, immutable event objects with fluent API
• ✅ Priority Support - Control listener execution order with priority levels
• ✅ Type Safe - PHP 8.2+ with strict types, readonly classes, and comprehensive PHPStan Level 10 coverage
• ✅ Fully Tested - 91 tests with comprehensive unit and integration coverage

Requirements

• PHP 8.2, 8.3, 8.4, or 8.5
• league/event ^3.0
• PSR-11 Container implementation (e.g., Laminas ServiceManager)

Installation

composer require webware/mezzio-eventdispatcher

Quick Start

1. Register the ConfigProvider

Add the configuration provider to your application:

// config/config.php use Webware\Event\ConfigProvider; $aggregator = new ConfigAggregator([ ConfigProvider::class, // ... other config providers ]); return $aggregator->getMergedConfig();

2. Create an Event

use Webware\Event\ImmutableEvent; // Immutable event (recommended for most use cases) $event = new ImmutableEvent('user.created', $user, ['timestamp' => time()]); // OR use mutable event when needed use Webware\Event\MutableEvent; $event = new MutableEvent('user.created', $user, ['timestamp' => time()]);

3. Create a Listener

use Webware\Event\EventInterface; use Webware\Event\ListenerInterface; class UserCreatedListener implements ListenerInterface { public function __invoke(EventInterface $event): void { $user = $event->getTarget(); $params = $event->getParams(); // Handle the event... } }

4. Register Listener in Configuration

// config/autoload/events.global.php use Webware\Event\ConfigKey; use Webware\Event\ListenerPriority; return [ ConfigKey::Listeners->value => [ [ 'event' => 'user.created', 'listener' => UserCreatedListener::class, 'priority' => ListenerPriority::Normal->value, ], ], 'dependencies' => [ 'factories' => [ UserCreatedListener::class => YourListenerFactory::class, ], ], ];

5. Dispatch Events

use Psr\EventDispatcher\EventDispatcherInterface; use Webware\Event\ImmutableEvent; class UserService { public function __construct( private EventDispatcherInterface $dispatcher ) {} public function createUser(array $data): User { $user = new User($data); // Dispatch immutable event $event = new ImmutableEvent('user.created', $user); $this->dispatcher->dispatch($event); return $user; } }

Documentation

Comprehensive documentation is available in the docs/ directory:

• Installation Guide - Detailed installation and setup instructions
• Basic Usage - Getting started with events, listeners, and dispatching
• Configuration - Configuration options and best practices
• Events - Creating and working with events
• Event Types - Understanding immutable vs mutable events
• Listeners - Creating and registering event listeners
• Subscribers - Using listener subscribers for complex event handling
• Priorities - Managing listener execution order
• Advanced Usage - Advanced patterns and techniques
• API Reference - Complete API documentation
• Testing - Testing your events and listeners

Example

A complete example demonstrating all features:

use Psr\EventDispatcher\EventDispatcherInterface; use Webware\Event\ImmutableEvent; // In your service class OrderService { public function __construct( private EventDispatcherInterface $dispatcher ) {} public function placeOrder(Order $order): void { // Process order... $order->setStatus('completed'); // Dispatch immutable event with context $event = new ImmutableEvent( name: 'order.completed', target: $order, params: [ 'user_id' => $order->getUserId(), 'total' => $order->getTotal(), 'timestamp' => time(), ] ); $this->dispatcher->dispatch($event); } } // Listener 1: Send confirmation email class OrderEmailListener implements ListenerInterface { public function __invoke(EventInterface $event): void { $order = $event->getTarget(); $this->emailService->sendOrderConfirmation($order); } } // Listener 2: Update inventory class OrderInventoryListener implements ListenerInterface { public function __invoke(EventInterface $event): void { $order = $event->getTarget(); $this->inventoryService->decrementStock($order); } } // Configuration return [ ConfigKey::Listeners->value => [ [ 'event' => 'order.completed', 'listener' => OrderEmailListener::class, 'priority' => ListenerPriority::Normal->value, ], [ 'event' => 'order.completed', 'listener' => OrderInventoryListener::class, 'priority' => ListenerPriority::High->value, // Runs first ], ], ];

Testing

This library includes comprehensive test suites:

# Run unit tests composer test # Run integration tests composer test-integration # Run all tests with coverage composer test-coverage # Run all quality checks (CS, PHPStan, tests) composer check

Code Quality

• PHPStan Level 10 - Maximum static analysis strictness
• Laminas Coding Standard - PSR-12 compliant with additional quality rules
• 100% Type Coverage - Strict types and comprehensive type hints
• Comprehensive Tests - 91 tests covering all functionality

Contributing

Contributions are welcome! Please ensure:

1. All tests pass: composer check
2. Code follows Laminas Coding Standard: composer cs-check
3. PHPStan Level 10 passes: composer static-analysis
4. New features include tests and documentation

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Credits

• Built on League Event by The PHP League
• Designed for Mezzio and Laminas applications

Support

• Issues: GitHub Issues
• Source: GitHub Repository