xobotyi/emittr

event library for your app

v2.0.2 2018-06-29 20:10 UTC

Requires

• php: >=7.1

Requires (Dev)

• codacy/coverage: ^1.4.0
• phpunit/phpunit: ^6.5.3

MIT

• Anton Zinovyev

• event
• event-emitter
• emitter
• event-management

README

About

emittr is a small dependency free 7.1+ library that gives you events functionality. It wont bring asyncronious execution, but will let you the best way to separate your code.
The main feature of emittr is global emitter with which you will be able to assign event callbacks even if class weren't autoloaded yet.
Library uses PSR-4 autoloader standard and always has 100% tests coverage.

Why emittr

1. It is well documented
2. I'm eating my own sweet pie=)
3. Assign event callbacks even if class wasn't yet autoloaded or even declared
4. Ability to stop the event propagation
5. Static and non-static variations of event emitter

Emittr's key feature is GlobalEventHandler which allow you to assign event listeners event if nor event emitter nor it's listener wasn't declared yet.
During lifecycle, event firstly propagates through all listeners assigned over it's emitter and then through listeners assigned over global handler, if event propagation wasn't stopped by any listener.

Requirements

• PHP 7.1+

Installation

Install it with composer

composer require xobotyi/emittr

Usage

use xobotyi\emittr;

class AwesomeClass extends emittr\EventEmitter
{
}

$awesomeObject = new AwesomeClass();

$awesomeObject
    ->once('testEvent', function (emittr\Event $e) {
        echo $e->getPayload()['message'] . PHP_EOL;
        $e->stopPropagation();
    })
    ->once('testEvent', function () { echo "emittr is awful!" . PHP_EOL; });

$awesomeObject->emit('testEvent', ['message' => "eittr is awesome!"]);

or you can use global emitter to assign handler

use xobotyi\emittr;

// note that neiter MostAwesomeClass class nor awesomeCallback function was not defined yet!
emittr\GlobalEventHandler::getInstance()
                         ->once("MostAwesomeClass", 'testEvent', 'awesomeCallback')
                         ->once("MostAwesomeClass", 'testEvent', 'nonAwesomeCallback');

class MostAwesomeClass
{
    use emittr\Traits\EventEmitterStatic;
}

function awesomeCallback(emittr\Event $e) {
    echo $e->getPayload()['message'] . PHP_EOL;
    $e->stopPropagation();
}

function nonAwesomeCallback() { echo "emittr is awful!" . PHP_EOL; }

MostAwesomeClass::emit('testEvent', ['message' => "eittr is awesome!"]);

Index

class \xobotyi\emittr\Event

• function stopPropagation() :self;
• function startPropagation() :self;
• function isPropagatable() :bool;
• function getEventName() :string;
• function getPayload() :mixed;
• function getSourceObject() :mixed;
• function getSourceClass() :?string

class \xobotyi\emittr\EventEmitter

• function emit($event, $payload = null) :self;
• function on(string $eventName, $callback) :self;
• function once(string $eventName, $callback) :self;
• function prependListener(string $eventName, $callback) :self;
• function prependOnceListener(string $eventName, $callback) :self;
• function off(string $eventName, $callback) :self;
• function removeAllListeners(?string $eventName = null) :self;
• function getEventNames() :array;
• function getListeners(?string $eventName = null) :array;
• function getMaxListenersCount() :int;
• function setMaxListenersCount(int $maxListenersCount) :self;
• function getGlobalEmitter() :Interfaces\GlobalEventHandler;
• function setGlobalEmitter(Interfaces\GlobalEventHandler $emitterGlobal) :self;

trait \xobotyi\emittr\Traits\EventEmitterStatic

• static function getEventEmitter() :EventEmitter;
• static function setEventEmitter(EventEmitter $eventEmitter) :EventEmitter;
• static function emit(string $eventName, $payload = null) :void;
• static function on(string $eventName, $callback) :void;
• static function once(string $eventName, $callback) :void;
• static function prependListener(string $eventName, $callback) :void;
• static function prependOnceListener(string $eventName, $callback) :void;
• static function off(string $eventName, $callback);
• static function removeAllListeners(?string $eventName = null) :void;
• static function getListeners(?string $eventName = null) :array;
• static function getMaxListenersCount() :int;
• static function setMaxListenersCount(int $maxListenersCount) :void;
• static function getGlobalEmitter() :GlobalEventHandler;
• static function setGlobalEmitter(GlobalEventHandler $emitterGlobal) :void;

class \xobotyi\emittr\GlobalEventHandler

• static function getInstance() :self;
• static function propagateEvent(Event $event, array &$eventsListeners) :bool;
• static function isValidCallback($callback) :bool;
• static function storeCallback(array &$arrayToStore, string $eventName, $callback, int $maxListeners = 10, bool $once = false, bool $prepend = false) :void;
• function loadListeners(array $listeners) :self;
• function on(string $className, string $eventName, $callback) :self;
• function once(string $className, string $eventName, $callback) :self;
• function prependListener(string $className, string $eventName, $callback) :self;
• function prependOnceListener(string $className, string $eventName, $callback) :self;
• function off(string $className, string $eventName, $callback) :self;
• function removeAllListeners(?string $className = null, ?string $eventName = null) :self;
• function getEventNames(string $className) :array;
• function getListeners(?string $className = null, ?string $eventName = null) :array;
• function getMaxListenersCount() :int;
• function setMaxListenersCount(int $maxListenersCount) :self;
• function propagateEventGlobal(Event $event) :bool;