README

PSR-14 compliant event dispatcher for WPZylos framework.

📖 Full Documentation | 🐛 Report Issues

✨ Features

• PSR-14 Compliant — Implements EventDispatcherInterface and ListenerProviderInterface
• Priority Listeners — Control execution order with numeric priorities
• Event Subscribers — Group multiple listeners in a single class
• Stoppable Events — Halt propagation with StoppableEvent base class
• Hierarchical Matching — Listeners trigger for parent classes and interfaces
• Container Integration — Auto-registered via EventServiceProvider

📋 Requirements

🚀 Installation

composer require KYNetCode/wpzylos-events

📖 Quick Start

use WPZylos\Framework\Events\EventDispatcher;
use WPZylos\Framework\Events\ListenerProvider;

// 1. Create the provider and dispatcher
$provider   = new ListenerProvider();
$dispatcher = new EventDispatcher($provider);

// 2. Register a listener on the provider
$provider->addListener(UserCreated::class, function (UserCreated $event) {
    mail($event->user->email, 'Welcome!', 'Thanks for signing up.');
});

// 3. Dispatch an event through the dispatcher
$dispatcher->dispatch(new UserCreated($user));

With the WPZylos container (after EventServiceProvider is registered):

// Resolve from the container
$provider   = $app->make(ListenerProvider::class);
$dispatcher = $app->make('events'); // or EventDispatcherInterface::class

$provider->addListener(UserCreated::class, fn(UserCreated $e) => /* handle */);
$dispatcher->dispatch(new UserCreated($user));

🏗️ Core Concepts

Event Classes

Events are plain PHP objects — no base class required:

class UserCreated
{
    public function __construct(
        public readonly User $user
    ) {}
}

class OrderPlaced
{
    public function __construct(
        public readonly Order $order,
        public readonly User $customer
    ) {}
}

Listeners

Register listeners on the ListenerProvider:

// Closure listener
$provider->addListener(UserCreated::class, function (UserCreated $event) {
    mail($event->user->email, 'Welcome!', 'Thanks for signing up.');
});

// Class method listener
$provider->addListener(UserCreated::class, [new SendWelcomeEmail(), 'handle']);

// With priority (lower = earlier, default: 10)
$provider->addListener(UserCreated::class, $logCreation, 5);

Subscribers

Group multiple listeners in a single class:

use WPZylos\Framework\Events\EventSubscriberInterface;

class UserEventSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            UserCreated::class => 'onUserCreated',
            UserDeleted::class => ['onUserDeleted', 5],
        ];
    }

    public function onUserCreated(UserCreated $event): void
    {
        // Handle creation
    }

    public function onUserDeleted(UserDeleted $event): void
    {
        // Handle deletion
    }
}

// Register through EventServiceProvider
$eventProvider = $app->make(EventServiceProvider::class);
$eventProvider->subscribe(new UserEventSubscriber());

Stoppable Events

Extend the StoppableEvent abstract class to create events that can halt propagation:

use WPZylos\Framework\Events\StoppableEvent;

class PaymentValidation extends StoppableEvent
{
    public bool $isValid = true;

    public function __construct(
        public readonly Payment $payment
    ) {}
}

// In a listener
$provider->addListener(PaymentValidation::class, function (PaymentValidation $event) {
    if ($event->payment->amount > 10000) {
        $event->isValid = false;
        $event->stopPropagation(); // Remaining listeners are skipped
    }
});

📦 Related Packages

📖 Documentation

For comprehensive documentation, tutorials, and API reference, visit wpzylos.com.

☕ Support the Project

• GitHub Sponsors
• PayPal Donate

📄 License

MIT License. See LICENSE for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Made with ❤️ by KYNetCode