This handly little module is very small, lightweight and well documented.
To setup an event you must call the static instance method, specifying the name / identifier of the event. This will return the event object.
Event::instance('menu.setup');
Events can also be retrieved using the instance method.
Event::instance('menu.setup');
The instance of the event with name menu.setup
is returned using this method.
To bind data to the event, use the bind method. This will bind data by reference. In this example i've created a basic setup menu event which binds the current object to the event.
Event::instance('menu.setup')
->bind('key', $value);
In contrast to binding, setting user data is not set by reference, and as such protected the state of the original object.
Event::instance('menu.setup')
->set('key', $value);
Note: All methods are chainable except the execute() and callbacks() method.
To have a function called when the event is executed, you can use the callback method to add your callback to the event.
Event::instance('menu.setup')
->callback(array($this, 'callback'));
Note: Make sure your callback matches the required event specific delegate and is publically accessible, otherwise an exception will be thrown.
On execute your callback will be called, and given the contents of the user data as parameters, with the event object at the end.
Your callback method should be of the same format as:
public function callback($1, $2, Event $event) { }
Where $1 and $2, represent variables, defined by the event delegate.
This is sometimes called dispatching, but is where every callback in the event object is called with the binded data.
Event::instance('menu.setup')
->execute();
Note: Do not execute the same event in a callback unconditionally otherwise reccursion will occur.
You can retrieve event callbacks using the callbacks()
method. This in conjunction with the reset()
method is useful for re-ordering callbacks within the event object.
Event::instance('menu.setup')
->callbacks();
An empty array will be returned if no callbacks have been added.
The reset()
method allows you to clear all callbacks from the event object. Use this method with caution as it could result in undesired effects. As said before this would mainly be used in conjunction with the callbacks()
method for re-ordering callbacks.
Event::instance('menu.setup')
->reset();
From inside a callback, the stop()
method will stop the execution of the current event. No other callbacks will be run after the current one completes. This method has no affect when run outside of callbacks.
Event::instance('menu.setup')
->stop();