Awesome
FuelPHP Event Package
Swift and elegant event management in PHP. A simple interface with a lot of power.
What's included
- Creating event containers for easy management.
- Registering and unregistering of events.
- Event prioritizing.
- Propagation of events can be prevented.
- A trait for eventable objects.
- Context binding to event handlers.
- Queues (with docs).
- Easy access through handy Facades (docs)
A simple example
<?php
$container = new Fuel\Event\Container();
$container->on('my_event', function($event){
// Act on the event
});
$container->trigger('my_event');
The special 'all' event
The only reserved event for Container
s and Queue
s is the 'all'
event. Listeners for this event
will be triggered on every event fired:
$container->on('all', function(){
echo 'This will also be fired!';
});
$container->trigger('event');
Unregistering of event
// Unregister all handlers for a specific event
$container->off('my_event');
// Unregister all handlers with a specific handler
$container->off(null, $my_handler);
// Unregister all handlers with a specific context
$conainer->off(null, null, $context);
Adding context
The value of $this
inside the handler (Closure) can be set by providing an object as the callback context.
$container->on('my_event', function($event){
// $this is now $myObject
}, $myObject);
Prioritizing events
Events can be prioritized with the addition of a priority number in the ->on
method.
$container->on('my_event', function(){
// This will be run last
}, 1);
$container->on('my_event', function(){
// This will be run first
}, 2);
Using contexts and prioritizing together
You can also combine contexts and prioritizing. In this scenario, first define the context and then supply the priority like so:
$container->on('my_event', function(){
// Do something
}, $context, 3);
Triggering events
You can trigger an event like so:
$container->trigger('my_event');
In some cases you'll want to pass arguments to the callback, every argument after the event name will be passed to the handler. Those arguments will be appended to the arguments array used to fire the handler. The first argument is always the event object. Following are the params you've profided in ->trigger()
.
$container->on('my_event', function($event, $param1, $param2){
// do stuff with $param1 and $param2
});
// Trigger the event with params.
$container->trigger('my_event', 'param 1', 'param 2');
Prevent event propagation
You can break the chain of event listeners by calling stopPropagation
on the event object.
$container->on('my_event', function($e){
$event->stopPropagation();
});
$container->on('my_event', function($e){
// This will not get executed.
});
$container->trigger('my_event');
Getting results
When an event is triggered, all the return values will be collected and returned.
$container->on('my_event', function(){
return 1;
});
$container->on('my_event', function(){
return 2;
});
$container->on('my_event', function(){
return 3;
});
$result = $container->trigger('my_event');
// [1, 2, 3]
Eventable objects
PHP 5.4 gives us traits
, an awesome way to share functionalities and allow for multiple inheritance. Models can become eventable when they use the Fuel\Event\Eventable
trait. Using it is pretty straight forward.
Implementing the trait
class EventableObject
{
// Incluse/use the trait
use \Fuel\Event\EventTrait;
}
// Get a new instance.
$myObject = new EventableObject();
Now your models/object instances have the power of events under their hood. So the following becomes possible:
$myObject = new EventableObject();
$myObject->on('event', function($event){
// act on the event
});
Configuration options
There are 2 configuration options to make it even easier to work with eventable objects, which can:
- make objects self binding,
- auto prepend itself to the arguments array.
Self binding objects
class EventableObject
{
use Fuel\Event\EventTrait;
// Set to true to bind itself as the callback context.
protected $_eventBindSelf = true;
}
$myObject = new EventableObject();
$myObject->on('event', function(){
// $this is now $myObject
});
You are still able to overwrite the context by supplying it.
$myObject->on('event', function(){
// $this is now $otherObject
}, $otherObject);
Self prepending object
Use this when you want to prepend the model to the arguments array.
<?php
class EventableObject
{
use Fuel\Event\EventTrait;
// Set to true to prepend itself to the arguments array.
protected $_eventPrependSelf = true;
}
$object = new EventableObject();
$object->on('event', function($event, $self){
// $self now is $object
});
When supplying params to the ->trigger
method they will be appended after the event and model:
$object->on('event', function($event, $self, $param1, $param2){
// Act on the event.
});
$object->trigger('event', 'param 1', 'param 2');