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:

All tests pass: composer check
Code follows Laminas Coding Standard: composer cs-check
PHPStan Level 10 passes: composer static-analysis
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

webware / mezzio-eventdispatcher

Maintainers

Details