alexpts/php-simple-events

Simple events and filters

3.1.0 2019-01-27 06:59 UTC

README

Codacy Badge SensioLabsInsight

Build Status Code Coverage Code Climate Scrutinizer Code Quality

Installation

$ composer require alexpts/php-simple-events

События

Класс Events предостовляет диспетчер событий. Обработчики подписываются на событие и будут выполнены в момент срабатывания события.

API Events

Класс предоставляет интерфейс EventsInterface, который содержит

emit($name, array $arguments = []);

on($name, callable $handler, $priority = 50, array $extraArguments = []);

once($name, callable $handler, $priority = 50, array $extraArguments = []);

off($name, callable $handler = null, $priority = null);

Добавление обработчиков

Обработчики добавляются через метод on к событию. Обработчиком события может быть любой callable тип:

use PTS\Events\Events;
$events = new Events;

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

Порядок обработчиков

На одно событие может быть подписано множество обработчиков. В момент добавления обработчика к событию через метод on можно указать приоритет срабатывания обработчика 3 параметром в виде числа. Обработчики с наивысшем приоритетом выполняются первые. Обработчики с одинаковым приоритетом выполняются в порядке добавления их к событию.

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

Отключение обработчиков

Любой обработчик может быть отписан от события с помощью метода off:

// 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 work

Фильтры

Фильтры очень похожи на события. В момент срабатывания события фильтрации нужно обязательно передать значение, которое будет пропущено через фильтры.

API Filters

Интерфейс фильтров полностью повторяет интерфейс событий в части подключения и отключения обработчиков. А вот вызов фильтра происходит с помощью метода filter вместо emit.

filter($name, $value, array $arguments = []);
on($name, callable $handler, $priority = 50, array $extraArguments = []);
once($name, callable $handler, $priority = 50, array $extraArguments = []);
off($name, callable $handler = null, $priority = null);

Пример

use PTS\Events\Filters;
$filters = new Filters;

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

Прерывание распространения фильтра

Чтобы прервать выполнение последующих обрабочтиков фильтра, необходимо кинуть исключение типа StopPropagation

$filters->on('eventName', function($value){ return $value . ' _'; });
$filters->on('eventName', function(value){ throw (new StopPropagation)->setValue(value); });
$filters->on('eventName', function(value){ return $value . ' 2';}); // it does not work
$title = $filters->filter('pre_title', ' Raw title!!!'); //  'Raw title!!! _'

Emitter

Trait EmitterTrait позволяет подмешать метод emit и filter к своему классу, позволяя выкидывать события в шину событий, либо пропускать значение через pipe (filters). Для этого помимо включения trait в класс, необходимо передать в класс шину событий, через метод setEvents/setFilters, в которую будут выкидываться события.