jbzoo / event
Library for event-based development
Installs: 613 738
Dependents: 6
Suggesters: 1
Security: 0
Stars: 26
Watchers: 6
Forks: 2
Open Issues: 0
Requires
- php: ^8.1
Requires (Dev)
- jbzoo/data: ^7.1
- jbzoo/toolbox-dev: ^7.1
README
The EventEmitter is a simple pattern that allows you to create an object that emits events, and allow you to listen to those events.
Install
composer require jbzoo/event
Simple example
use JBZoo\Event\EventManager; $eManager = new EventManager(); // Simple $eManager->on('create', function () { echo "Something action"; }); // Just do it! $eManager->trigger('create');
Set priority
By supplying a priority, you are ensured that subscribers handle in a specific order. The default priority is EventManager::MID. Anything below that will be triggered earlier, anything higher later. If there are two subscribers with the same priority, they will execute in an undefined, but deterministic order.
// Run it first $eManager->on('create', function () { echo "Something high priority action"; }, EventManager::HIGH); // Run it latest $eManager->on('create', function () { echo "Something another action"; }, EventManager::LOW); // Custom index $eManager->on('create', function () { echo "Something action"; }, 42); // Don't care... $eManager->on('create', function () { echo "Something action"; });
Types of Callback
All default PHP callbacks are supported, so closures are not required.
$eManager->on('create', function(){ /* ... */ }); // Custom function $eManager->on('create', 'myFunction'); // Custom function name $eManager->on('create', ['myClass', 'myMethod']); // Static function $eManager->on('create', [$object, 'Method']); // Method of instance
Cancel queue of events
use JBZoo\Event\ExceptionStop; $eManager->on('create', function () { throw new ExceptionStop('Some reason'); // Special exception for JBZoo/Event }); $eManager->trigger('create'); // return 'Some reason' or TRUE if all events done
Passing arguments
Arguments can be passed as an array.
$eManager->on('create', function ($entityId) { echo "An entity with id ", $entityId, " just got created.\n"; }); $entityId = 5; $eManager->trigger('create', [$entityId]);
Because you cannot really do anything with the return value of a listener, you can pass arguments by reference to communicate between listeners and back to the emitter.
$eManager->on('create', function ($entityId, &$warnings) { echo "An entity with id ", $entityId, " just got created.\n"; $warnings[] = "Something bad may or may not have happened.\n"; }); $warnings = []; $eManager->trigger('create', [$entityId, &$warnings]);
Namespaces
$eManager->on('item.*', function () { // item.init // item.save echo "Any actions with item"; }); $eManager->on('*.init', function () { // tag.init // item.init echo "Init any entity"; }); $eManager->on('*.save', function () { // tag.save // item.save echo "Saving any entity in system"; }); $eManager->on('*.save.after', function () { // tag.save.after // item.save.after echo "Any entity on after save"; }); $eManager->trigger('tag.init'); $eManager->trigger('tag.save.before'); $eManager->trigger('tag.save'); $eManager->trigger('tag.save.after'); $eManager->trigger('item.init'); $eManager->trigger('item.save.before'); $eManager->trigger('item.save'); $eManager->trigger('item.save.after');
Summary benchmark info (execution time) PHP v7.4
All benchmark tests are executing without xdebug and with a huge random array and 100.000 iterations.
Benchmark tests based on the tool phpbench/phpbench. See details here.
Please, pay attention - 1μs = 1/1.000.000 of second!
benchmark: ManyCallbacks
benchmark: ManyCallbacksWithPriority
benchmark: OneCallback
benchmark: Random
Unit tests and check code style
make update make test-all
License
MIT