Event Component

Creating Base Emitters

$emitter = new EventEmitter();

Creating Asynchronous Emitters

$emitter = new EventEmitter($loop); // $loop should be instance of \Kraken\Loop\Loop

Emitting Events

Emitting event notifies all listeners to call their corresponding callbacks. All callbacks are executed in the same order as they were attached. This method is blocking for base emitters and non-blocking for asynchronous ones.

$emitter->emit('eventName', $eventParams = [ 'param1', 'param2' ]);

Attaching Listeners

Listeners attached via on method will be executed each time the event is presented.

$emitter->on('eventName', function($param1, $param2) {
    // do something with event
});

Attaching Single Execution Listeners

Listeners attached via once method will be executed only once and after that the listener is unregistered automatically.

$emitter->once('eventName', function() {
    // this handler will be executed only once
});

Attaching Multiple Execution Listeners

Listeners attached via times method will be executed as many times as second argument implies. After that, the listener is unregistered automatically.

$emitter->times('eventName', 3, function() {
    // this handler will be executed exactly 3 times 
});

Delaying Listeners

All of on, once and times events have a special delay prefixed alternatives that instead of being applied instantly, starts to be executed after specified amount of events have been emitted.

$emitter->delayOnce('eventName', 2, function() {
    // this handler will be executed once when eventName is emitted 2nd time
});

$emitter->delayTimes('eventName', 2, 1, function() {
    // this works the same as previous example
});

Cancelling Listeners

All attached listeners can be cancelled, meaning they will be unregistered from event emitter.

It can be done via calling cancel method on handler you want to cancel.

$handler = $emitter->on('eventName', $callback);
$handler->cancel();

Cancelling can be also done indirectly using emitter.

$emitter->on('eventName', $callback);
$emitter->removeListener('eventName', $callback);

Forwarding & Discarding Events

Events can be forwarded between two or more event emitters using forwardEvents method. Forwarding works in that way, when emitter A forwards its events to emitter B, then all listeners attached on B will receive event emitted on both A and B. It works only in one way, so event emitted on B won't be visible for A listeners.

$emitterA = new EventEmitter();
$emitterB = new EventEmitter();

$emitterA->forwardEvents($emitterB);
$emitterB->on('event', $callback);

$emitterA->emit('event'); // this event will be forwarded (copied) to emitter B, and $callback will be executed.
$emitterA->discardEvents($emitterB); // now longer any events will be forwarded

forwardEvents automatically passes all emitted events to its target. This might be not always desired behaviour. If you want to forward only specified set of events, then consider using copyEvents method.

$emitterA = new EventEmitter();
$emitterB = new EventEmitter();

$emitterA->copyEvents($emitterB, [ 'event' ]); // only 'event' event will be forwarded.