L O A D I N G
Edit this page

Event Component

Introduction

Kraken/Event component provides classes to implement event-based architecture.

Features

Kraken/Event features:

  • Both asynchronous and synchronous event emitters
  • Event handlers
  • Expanded interface for attaching listeners and managing events propagation
  • Kraken Framework compatibility

Concepts

Event-driven Architecture

Event-driven architecture is a software architecture pattern promoting applications and systems which transmit events among loosely coupled components and services. This kind of systems usually consists of event emitters and event listeners.

Event Emitter

Event emitter is an object which purpose is to emit and transfer events.

Event Listener

Event listener is an object which detects event presentation and reacts to it by calling corresponding event handler.

Event

Event can be defined as a change in application state.

Examples

This section contains examples and patterns that can be used with described 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.

Important Classes & Interfaces

This section contains list of most important classes and interfaces shipped with this component. It does not include all classes and interface.

AsyncEventEmitter

class AsyncEventEmitter implements EventEmitterInterface, LoopAwareInterface

AsyncEventEmitter is implementation of asynchronous event emitter.

BaseEventEmitter

class BaseEventEmitter implements EventEmitterInterface

BaseEventEmitter is implementation of synchronous event emitter.

EventEmitter

class EventEmitter implements EventEmitterInterface

EventEmitter is universal event emitter that by default behaves as synchronous emitter, but changes to asynchronous when provided with loop instance.

EventEmitterInterface

interface EventEmitterInterface

EventHandler

class EventHandler

EventHandler represents single event listening callback.

Start from the Beginning