README

An enterprise-grade, highly modular, PSR-14 compliant Event Dispatcher component. Designed with high-performance prioritizations, class inheritance listener resolution, and flexible subscriber architectures, it acts as the decoupled central nervous communication system for complex PHP systems.

Features

• ⚡ PSR-14 Compliant: Implements standard psr/event-dispatcher interfaces, making it fully interoperable with standard PHP frameworks.
• 📈 Prioritized Listener Execution: Easily assign custom weights/priorities to listeners to enforce strict execution flows.
• 🛡️ Stoppable Propagation: Leverage stoppable events (extending AbstractStoppableEvent) to allow critical listeners to halt downstream propagation on demand.
• 🧩 Class & Interface Inheritance Resolution: Listeners bound to parent classes or interfaces are automatically resolved and executed when child events are dispatched!
• 🔄 Event Subscribers (Symfony-style): Bundle multiple event listeners cleanly inside a single subscriber class using EventSubscriberInterface.
• 🔗 Composite Aggregation: Aggregate multiple listener providers into a single unified chain using the advanced AggregateListenerProvider pattern.
• ✨ Zero Runtime Dependencies: Extremely fast, clean, and highly modular.

Installation

Add this package to your project using Composer (ensure your local repository mapping is configured):

composer require yaknet/event-dispatcher

Quick Start

1. Basic Prioritized Event Dispatching

Define a custom event and register prioritized closures:

<?php

require 'vendor/autoload.php';

use YakNet\EventDispatcher\Dispatcher\EventDispatcher;
use YakNet\EventDispatcher\Provider\ListenerProvider;

class OrderPlacedEvent
{
    public int $orderId;
    public float $amount;

    public function __construct(int $orderId, float $amount)
    {
        $this->orderId = $orderId;
        $this->amount = $amount;
    }
}

// 1. Setup providers and dispatcher
$provider = new ListenerProvider();
$dispatcher = new EventDispatcher($provider);

// 2. Attach prioritized listeners
$provider->addListener(OrderPlacedEvent::class, function (OrderPlacedEvent $e) {
    echo "✉ Sending order confirmation email...\n";
}, 0);

$provider->addListener(OrderPlacedEvent::class, function (OrderPlacedEvent $e) {
    echo "🛡 [HIGHEST PRIORITY] Performing security fraud check...\n";
}, 100); // Priority 100 executes before priority 0!

// 3. Dispatch the event!
$dispatcher->dispatch(new OrderPlacedEvent(42, 199.99));

2. Creating an Event Subscriber (Symfony Style)

Group multiple related event listeners cleanly inside a subscriber class:

<?php

use YakNet\EventDispatcher\Contract\EventSubscriberInterface;

class SystemRecoverySubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            CircuitBreakerTrippedEvent::class => 'onCircuitBreakerTripped',
            ConnectionFailedEvent::class      => ['onConnectionFailed', 50],
        ];
    }

    public function onCircuitBreakerTripped(CircuitBreakerTrippedEvent $event): void
    {
        // Recovery logic...
    }

    public function onConnectionFailed(ConnectionFailedEvent $event): void
    {
        // Re-routing logic...
    }
}

// Register easily in the provider:
$provider->addSubscriber(new SystemRecoverySubscriber());

Verification & Testing

Verify that all priority hierarchies and inheritance resolution tests pass cleanly:

composer test

Perform static analysis with PHPStan:

composer analyze

License

This project is licensed under the MIT License - see the LICENSE file for details.