webino / event-emitter
Event Emitter implementation.
Requires
- php: ~7.1
- webino/exceptions: 1.*
Requires (Dev)
- nette/tester: 1.*
- phpstan/phpstan: 0.*
- squizlabs/php_codesniffer: 3.*
- tracy/tracy: 2.*
This package is auto-updated.
Last update: 2024-10-18 14:19:10 UTC
README
Event Emitter implementation.
Recommended Usage
Use event emitter to decouple routine algorithm from an extended logic.
Setup
composer require webino\event-emitter
Quick Use
Emitting an event:
use Webino\EventEmitter; $emitter = new EventEmitter; // registering closure event handler $emitter->on('example', function () { return 'Hello'; }); // emitting custom event $event = $emitter->emit('example'); /** @var \Webino\EventResults $results */ $results = $event->getResults(); echo $results; // => Hello
Removing an event handler:
use Webino\EventEmitter; $emitter = new EventEmitter; $handler = function () { return 'Hello'; }; $emitter->on('example', $handler); // remove handler for all events $emitter->off($handler); // remove all handlers for an event $emitter->off(null, 'example'); // remove all handlers for all events $emitter->off();
Emitting an event until:
use Webino\EventEmitter; $emitter = new EventEmitter; $emitter->on('example', function () { return 'Special'; }); $event = $emitter->emit('example', function ($result) { // when result meets required condition if ('Special' === $result) { // stop propagation return false; } // or continue return true; });
Event handling priority:
use Webino\EventEmitter; $emitter = new EventEmitter; $emitter->on('example', function () { return 'Begin'; }, $event::BEGIN); $emitter->on('example', function () { return 'Before'; }, $event::BEFORE); $emitter->on('example', function (Event $event) { return 'Main'; }, $event::MAIN); $emitter->on('example', function () { return 'After'; }, $event::AFTER); $emitter->on('example', function () { return 'Finish'; }, $event::FINISH); // emitting custom event $event = $emitter->emit('example'); /** @var \Webino\EventResults $results */ $results = $event->getResults(); echo $results; // => BeginBeforeMainAfterFinish
Event handler:
use Webino\EventEmitter; use Webino\EventHandlerInterface; use Webino\EventHandlerTrait; class ExampleEventHandler implements EventHandlerInterface { use EventHandlerTrait; protected function initEvents(): void { $this->on('example', function () { return 'Foo'; }); $this->on('example', function () { return 'Bar'; }); } } // emitting custom event $event = $emitter->emit('example'); /** @var \Webino\EventResults $results */ $results = $event->getResults(); echo $results; // => FooBar
API
Event
-
const BEGIN
The beginning priority of the event. -
const BEFORE
Priority before main event. -
const MAIN
Main event priority. -
const AFTER
Priority after main event. -
const FINISH
Priority at the end of the event. -
const OFFSET
Event priority offset. -
string getName()
Get event name. -
EventEmitterInterface getTarget()
Get target object from which event was emitted. -
mixed getValue(string $name, mixed $default = null)
Get event value by name. -
void setValues(iterable $values)
Set event values. -
EventResults getResults()
Returns event results. -
void stop(bool $stop = true)
Indicate whether or not to stop this event. -
bool isStopped()
Indicates should stop.
EventEmitter
-
void setEventDispatcher(EventDispatcherInterface $dispatcher)
Inject event dispatcher. -
void on(
string|EventInterface|EventHandlerInterface $event,
string|array<int, string>|callable $callback = null,
int $priority = 1)
Set event handler. -
void off(callable|EventHandlerInterface $callback = null, string|EventInterface $event = null)
Remove event handler. -
EventInterface emit(string|EventInterface $event, callable $until = null)
Invoke handlers.
EventResults
-
mixed|null first()
Returns first response. -
mixed|null last()
Returns last response.
EventHandler
-
void attachEventEmitter(EventDispatcherInterface $emitter)
Attach event emitter to handler. -
void detachEventEmitter(EventDispatcherInterface $emitter)
Detach event emitter from handler.
Architecture
It is possible to have a global dispatcher to attach event handlers to.
Event Lifecycle
The basic idea around events is that we just trigger an event and every action happens in handlers, even the main action. Then we can listen to that event using priorities, if we want to act like a middleware. The event propagation could be stopped at any time.
Using events like someEvent.pre and someEvent.post or someEvent.before, someEvent.after, it doesn't matter, is messy and not recommended, don't do that. Give an event a unique name then attach handlers, main action including, using priorities. Convenient way to do that is to use an event priority constants.
Development
Static analysis:
composer analyse
Coding style check:
composer check
Coding style fix:
composer fix
Testing:
composer test
Git pre-commit setup:
ln -s ../../pre-commit .git/hooks/pre-commit
Addendum
Please, if you are interested in this library report any issues and don't hesitate to contribute. We will appreciate any contributions on development of this library.