alexpts/php-simple-events

Simple events and filters

php-simple-events

, _(*1)

EventEmitter

It is very fast event emitter and filters., _(*2)

Installation

$ composer require alexpts/php-simple-events, _(*3)

Usage

Creating an Emitter

$emitter = new \PTS\Events\EventEmitter;

Adding Listeners

Callable handler, _(*4)

$emitter->on('user.created', function (User $user) use ($logger) {
    $logger->log(sprintf("User '%s' was created.", $user->getLogin()));
});

With priority, _(*5)

$emitter->on('user.created', $handler, 100);

With extra arguments for EventEmitterExtraArgs instance (EventEmitter instance ignores extra args), _(*6)

$emitter = new \PTS\Events\EventEmitterExtraArgs;

$extra1 = 1;
$extra2 = 'some';

$handler = function(string $log, int $extra1, string $extra2) {
   // ...
};

$emitter->on('log', $handler, 50, [$extra1, $extra2]);
$emitter->emit('log', ['some log']);

Removing Listeners

Remove concrete handler, _(*7)

$handler = fn() => 'log';
$emitter->on('log', $handler)
$emitter->off('log', $handler);

Remove all handlers, _(*8)

$emitter->off('log');

Remove concrete handler with priority, _(*9)

$emitter->off('log', $handler, 100);

Emitting Events

Simple emit, _(*10)

$emitter->emit('log');

Pass arguments on emit, _(*11)

$emitter->on('log', function(string $log, int $a2, bool $a3) {
    // ...
});
$emitter->emit('log', ['arg1', 2, true]);

Interface

emit(string $name, array $args = []): self;
on(string $name, callable $handler, int $priority = 50, array $extraArgs = []): self;
once(string $name, callable $handler, int $priority = 50, array $extraArgs = []): self;
off(string $event, callable $handler = null, int $priority = null): self;

listeners(string $event = null): array;
eventNames(): array;
 ```

#### EventHandler
EventHandler must be `callable`

```php
$eventsBus = new \PTS\Events\EventEmitter;

$eventsBus->on('some:event', function(){ ... });
$eventsBus->on('some:event', 'trim');
$eventsBus->on('some', ['ClassName', 'method']);
$eventsBus->on('some', [$this, 'method']);
$eventsBus->once('some', $instanceWithInvokeMethod);

Order handlers

Listeners have priority. All listeners invoke by priority, _(*12)

$events->on('post:title', 'trim', 10); // second
$events->on('post:title', 'prepareTitle', 70); // first

Remove handler

// remove handler 'trim' with priority = 10
$events->on('post:title', 'trim', 10);
$events->off('post:title', 'trim', 10);

// remove all handler 'trim' with any priority
$events->on('post:title', 'trim', 10);
$events->off('post:title', 'trim');

// remove all handlers
$events->on('post:title', 'trim', 10);
$events->off('post:title');

StopPropagation

$events->on('eventName', function() { ... });
$events->on('eventName', function() { throw new StopPropagation; });
$events->on('eventName', function() { ... }); // it does not call

Filters

API Filters

Filters is very similar to EventEmitter. Filter passes first value through all listeners and returns modified value., _(*13)

emit(string $name, $value, array $args = []);
on(string $name, callable $handler, int $priority = 50, array $extraArgs = []): self;
once(string $name, callable $handler, int $priority = 50, array $extraArgs = []): self;
off(string $event, callable $handler = null, int $priority = null): self;

listeners(string $event = null): array;
eventNames(): array;

Example, _(*14)

$filters = new \PTS\Events\Filters;

$filters->on('post:title', 'trim');
$title = $filters->filter('post:title', '   Raw title   '); // `Raw title`

Inject EventEmitter / FilterEmitter

1. Event/Filter Bus.

use PTS\Events\Bus\EventBusTrait;

class Service {
    use EventBusTrait;

    public function getPost()
    {
        $post = ...;
        // you can to modify $post via filter/event
        $post = $this->filter('getPost', $post); // from EventBusTrait
        return $post;
    }
}

1. Event/Filter for any object.

Extend from EventEmitter:, _(*15)

use PTS\Events\Filter\FilterEmitter;
use PTS\Events\EventEmitter;

class Request extend FilterEmitter { // extend EventEmitter

    public function parseHeader()
    {
        $rawHttpRequest = '...';
        $headers = $this->filter('parseHeader', $rawHttpRequest);
        return $headers;
    }
}

$request = new Request;
$parseHeader = new ParserHeader;
$request->on('parseHeader', [$parseHeader, 'parse']);
$headers = $request->parseHeader();

Use trait:, _(*16)

use PTS\Events\Filter\FilterEmitterTrait;
use PTS\Events\EventEmitterTrait;

class Request

    use FilterEmitterTrait;

    public function parseHeader()
    {
        $rawHttpRequest = '...';
        $headers = $this->filter('parseHeader', $rawHttpRequest);
        return $headers;
    }
}

$request = new Request;
$parseHeader = new ParserHeader;
$request->on('parseHeader', [$parseHeader, 'parse']);
$headers = $request->parseHeader();