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