alexpts/php-simple-events

Simple events and filters

6.0.1 2023-01-05 09:51 UTC

Requires

• php: >=8.1

Requires (Dev)

• blackfire/php-sdk: ^1.31
• phpbench/phpbench: ^1.2
• phpunit/phpunit: ^9.5

MIT

• Alexpts

• event-dispatcher
• event
• filter
• event-emitter
• emitter

README

EventEmitter

It is very fast event emitter and filters.

Installation

$ composer require alexpts/php-simple-events

Usage

Creating an Emitter

$emitter = new \PTS\Events\EventEmitter;

Adding Listeners

Callable handler

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

With priority

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

With extra arguments for EventEmitterExtraArgs instance (EventEmitter instance ignores extra args)

$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

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

Remove all handlers

$emitter->off('log');

Remove concrete handler with priority

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

Emitting Events

Simple emit

$emitter->emit('log');

Pass arguments on emit

$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

$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

$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.

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

$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:

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:

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();