README

Publish. Subscribe. Regret.

A simple PHP library for event handling implementing the Publisher-Subscriber pattern. Allows creating "loosely" coupled components through an event emission and listening system.

Installation

composer require coders/events

Basic Usage

1. Creating EventBus

<?php
require_once 'vendor/autoload.php';

use Coders\Events\EventBus;
use Coders\Events\Event;

$eventBus = new EventBus();

2. Registering listeners

// Simple listener
$eventBus->on('user.registered', function(Event $event) {
    echo "New user: " . $event->data['name'] . "\n";
});

// Listener with target
$eventBus->on('notification', function(Event $event) {
    echo "Email sent to: " . $event->data['email'] . "\n";
}, 'email');

$eventBus->on('notification', function(Event $event) {
    echo "SMS sent to: " . $event->data['phone'] . "\n";
}, 'sms');

3. Emitting events

// Simple event
$event = new Event('user.registered', [
    'name' => 'John Doe',
    'email' => 'john@example.com'
]);
$eventBus->emit($event);

// Event with specific target
$emailEvent = new Event('notification', [
    'email' => 'john@example.com',
    'message' => 'Welcome!'
], 'email');
$eventBus->emit($emailEvent);

Classes

Event

Represents an event in the system.

Properties:

string $type - event type
mixed $data - data associated with the event (optional)
string|null $target - specific target for the event (optional)

Constructor:

new Event(string $type, mixed $data = null, ?string $target = null)

EventBus

Main class for managing events.

Methods:

on(string $eventType, callable $callback, ?string $target = null): self - registers a listener
emit(Event $event): mixed - emits an event to registered listeners

Listener

Class handling callbacks for a specific event type.

Methods:

addCallback(callable $callback, ?string $id = null): self - adds a callback
handle(Event $event): mixed - handles an event by calling appropriate callbacks

Usage Examples

Example 1: Notification System

<?php
use Coders\Events\EventBus;
use Coders\Events\Event;

$eventBus = new EventBus();

// Register different notification methods
$eventBus->on('order.completed', function(Event $event) {
    $order = $event->data;
    echo "Sending email for order #{$order['id']}\n";
}, 'email');

$eventBus->on('order.completed', function(Event $event) {
    $order = $event->data;
    echo "Sending SMS for order #{$order['id']}\n";
}, 'sms');

$eventBus->on('order.completed', function(Event $event) {
    $order = $event->data;
    echo "Updating status for order #{$order['id']}\n";
}, 'status_update');

// Emit event
$order = ['id' => 12345, 'customer' => 'John Doe'];
$eventBus->emit(new Event('order.completed', $order));

// Send only email
$eventBus->emit(new Event('order.completed', $order, 'email'));

Example 2: Logging System

<?php
use Coders\Events\EventBus;
use Coders\Events\Event;

$eventBus = new EventBus();

// Different logging levels
$eventBus->on('log', function(Event $event) {
    $message = $event->data['message'];
    error_log("[ERROR] $message");
}, 'error');

$eventBus->on('log', function(Event $event) {
    $message = $event->data['message'];
    echo "[INFO] $message\n";
}, 'info');

$eventBus->on('log', function(Event $event) {
    $message = $event->data['message'];
    echo "[DEBUG] $message\n";
}, 'debug');

// Logging
$eventBus->emit(new Event('log', ['message' => 'Database connection error'], 'error'));
$eventBus->emit(new Event('log', ['message' => 'User logged in'], 'info'));

Example 3: Return Values

<?php
use Coders\Events\EventBus;
use Coders\Events\Event;

$eventBus = new EventBus();

$eventBus->on('calculate.sum', function(Event $event) {
    $numbers = $event->data;
    return array_sum($numbers);
});

$result = $eventBus->emit(new Event('calculate.sum', [1, 2, 3, 4, 5]));
echo "Sum: $result\n"; // Sum: 15

Features

Targeting

You can target events to specific listeners using the target parameter:

// Register listeners with different targets
$eventBus->on('process', $callback1, 'fast');
$eventBus->on('process', $callback2, 'slow');
$eventBus->on('process', $callback3); // no target

// Call only 'fast' listener
$eventBus->emit(new Event('process', $data, 'fast'));

// Call all listeners (when no target in event)
$eventBus->emit(new Event('process', $data));

Fluent Interface

EventBus supports fluent interface for easy method chaining:

$eventBus
    ->on('user.login', $loginCallback)
    ->on('user.logout', $logoutCallback)
    ->on('user.register', $registerCallback);

Requirements

PHP 8.0 or higher

Author

Irek Kubicki - github@ixdude.com

License

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

coders / events

Maintainers

Details