README

Soochak (सूचक) - A modern, PSR-14 compliant event dispatcher for PHP 8.2+

Soochak is a lightweight, high-performance event management library that implements the PSR-14 Event Dispatcher standard. It provides a simple yet powerful API for implementing the observer pattern in your PHP applications.

Features

• ✅ PSR-14 Compliant - Full implementation of EventDispatcherInterface and ListenerProviderInterface
• ✅ Backward Compatible - Legacy API maintained for existing codebases
• ✅ Priority Support - Control listener execution order with priority queues
• ✅ Event Propagation - Stop event propagation when needed
• ✅ Type Safe - Full PHP 8.2+ type hints and union types
• ✅ Memory Efficient - Uses generators for lazy listener iteration
• ✅ 100% Test Coverage - Comprehensive test suite with 50+ tests
• ✅ Zero Dependencies - Only requires PSR-14 interfaces

Requirements

• PHP 8.2 or higher
• Composer

Installation

Install via Composer:

composer require vaibhavpandeyvpz/soochak

Quick Start

Basic Usage

<?php

use Soochak\EventManager;
use Soochak\Event;

$em = new EventManager();

// Attach a listener to an event (using class name)
$em->attach(Event::class, function (Event $event) {
    echo "Event dispatched!";
});

// Dispatch the event
$em->dispatch(new Event());

Using PSR-14 Standard API

<?php

use Soochak\EventManager;
use Soochak\Event;

$em = new EventManager();
$event = new Event();

// Attach listener
$em->attach(Event::class, function (object $event) {
    // Handle the event
});

// Dispatch using PSR-14 interface
$em->dispatch($event);

Usage Examples

Priority-Based Listeners

Listeners with higher priority values are executed first:

$em = new EventManager();

// Lower priority (executed last)
$em->attach(Event::class, function (Event $event) {
    echo "Sending email notification...\n";
}, 10);

// Higher priority (executed first)
$em->attach(Event::class, function (Event $event) {
    echo "Updating inventory...\n";
}, 20);

$em->dispatch(new Event());
// Output:
// Updating inventory...
// Sending email notification...

Event Propagation Control

Stop further listeners from executing:

$em = new EventManager();

$em->attach(Event::class, function (Event $event) {
    $event->stopPropagation(true);
    echo "Validation failed, stopping propagation\n";
});

$em->attach(Event::class, function (Event $event) {
    echo "This won't execute if propagation was stopped\n";
});

$event = new Event();
$em->dispatch($event);

Working with Event Objects

use Soochak\Event;

// Create an event
$event = new Event();

// Stop propagation if needed
$event->stopPropagation(true);

// Check if propagation is stopped
if ($event->isPropagationStopped()) {
    echo "Propagation is stopped\n";
}

// Dispatch the event
$em->dispatch($event);

Custom Event Objects

You can use any object as an event:

class UserRegisteredEvent
{
    public function __construct(
        public readonly int $userId,
        public readonly string $email
    ) {}
}

$em = new EventManager();

// Attach listener using class name
$em->attach(UserRegisteredEvent::class, function (UserRegisteredEvent $event) {
    echo "User {$event->userId} registered with email {$event->email}\n";
});

// Or attach using instance
$event = new UserRegisteredEvent(123, 'user@example.com');
$em->attach($event, function (UserRegisteredEvent $e) {
    // Handle event
});

// Dispatch
$em->dispatch($event);

Managing Listeners

$em = new EventManager();

$listener = function (Event $event) {
    echo "Listener executed\n";
};

// Attach
$em->attach(Event::class, $listener);

// Detach
$em->detach(Event::class, $listener);

// Clear all listeners for an event
$em->clear(Event::class);

Getting Listeners for an Event

$em = new EventManager();

$em->attach(Event::class, function () {}, 10);
$em->attach(Event::class, function () {}, 20);

$event = new Event();
$listeners = iterator_to_array($em->getListenersForEvent($event));

echo count($listeners); // 2

API Reference

EventManager

The main event manager class implementing PSR-14 interfaces.

Methods

• attach(string|object $event, callable $callback, int $priority = 0): void - Attach a listener to an event
• detach(string|object $event, callable $callback): bool - Remove a specific listener
• clear(string|object $event): void - Clear all listeners for an event
• dispatch(object $event): object - Dispatch an event (PSR-14)
• getListenersForEvent(object $event): iterable - Get all listeners for an event (PSR-14)

Event

Minimal event implementation implementing StoppableEventInterface.

Methods

• isPropagationStopped(): bool - Check if propagation is stopped
• stopPropagation(bool $flag = true): void - Stop event propagation

PSR-14 Compliance

Soochak fully implements the PSR-14 Event Dispatcher standard:

• ✅ Psr\EventDispatcher\EventDispatcherInterface
• ✅ Psr\EventDispatcher\ListenerProviderInterface
• ✅ Psr\EventDispatcher\StoppableEventInterface (via Event class)

You can use Soochak with any PSR-14 compatible library or framework.

Testing

The project includes a comprehensive test suite with 100% code coverage:

# Run tests
vendor/bin/phpunit

# Run with coverage
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text

# Generate HTML coverage report
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html coverage

Performance

Soochak is designed for performance:

• Lazy Evaluation - Uses generators to avoid loading all listeners into memory
• Direct Callbacks - Uses direct function calls instead of call_user_func()
• Efficient Queues - Priority queues with FIFO ordering for same-priority listeners
• Minimal Overhead - Zero dependencies beyond PSR-14 interfaces

Architecture

Components

• EventManager - Main dispatcher implementing PSR-14 interfaces, manages listener registration and retrieval
• Event - Standard event implementation
• EventListenerQueue - Priority queue for listener ordering

Design Patterns

• Observer Pattern - Event/listener architecture
• Strategy Pattern - Pluggable listener providers
• Priority Queue - Efficient listener ordering

License

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

Author

Vaibhav Pandey

• Email: contact@vaibhavpandey.com
• Homepage: https://github.com/vaibhavpandeyvpz/soochak

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

Version 2.0.0 (Current)

• ✅ Upgraded to PHP 8.2+
• ✅ Full PSR-14 compliance
• ✅ Modern type hints and union types
• ✅ 100% test coverage
• ✅ Performance optimizations
• ✅ Comprehensive documentation

Version 1.0.0 (Legacy)

• Initial release with PHP 5.3+ support
• Basic event management functionality

Soochak - Simple, powerful, and standards-compliant event management for PHP.