eac_events

Source Code: eac_events.class

Download eac_events.zip

Google Code project page

Interested in using this software in your project? Contact Kevin at KBurkholder@EarthAsylum.com

This work is licensed under the Creative Commons GNU-LGPL License.
Licensing & Registration
 

Donations are greatly appreciated and help fund further development and maintain the LGPL licensing.

• Follow me on Twitter for software updates, releases and announcements.

A simple event management implementation (event dispatch/fire, event handler/listener). Supports unlimited events, unlimited listeners per event, event propagation, and the ability to stop propagation. Event dispatchers may pass values to event listeners and listeners may modify those values returned to the dispatcher.

There are no restrictions on event names but it is recommended that a namespace:eventname scheme be used (i.e. 'myapp:myevent') to avoid conflicting event names.

Version 3 incorporates significant changes over previous versions including changes to the fire() method.
The new dispatch() method functions as the previous fire() method did and the fire() method only fires an event when there are listeners.
New methods: dispatch(), fireOnce(), wasFired(), hasListeners()

Methods:

Event::listen($eventName, $callback [,$arguments])

Adds an event listener/handler.

$eventName is the name of an event to listen for.

$callback is the function or method to be executed when the event fires.

$arguments is/are any additional values that are passed to $callback when the event fires. These values are passed in the $event->listener->values array.

Returns the listener object.

Event::ignore($listener)

Removes an event listener/handler.

$listener is the listener object returned from Event::listen() or the $event->listener property.

Returns true if the listener was found and removed, otherwise false.

Event::fire($eventName [,$arguments])

Fires/dispatches an event only if it has listeners.
Calls Event::dispatch but checks to make sure that there are registered listeners.

$eventName is the name of the event to fire.

$arguments is/are any additional values that are passed to the listener callback(s). These values are passed as arguments to the callback function/method and in the $event->args property by reference and may be modified by the callback function.

Returns the EventObject or false (if not dispatched).

Event::fireOnce($eventName [,$arguments])

Fires/dispatches an event only once and only if it has listeners.
Calls Event::dispatch but checks to make sure the event hasen't been fired before
and that there are registered listeners.

$eventName is the name of the event to fire.

$arguments is/are any additional values that are passed to the listener callback(s). These values are passed as arguments to the callback function/method and in the $event->args property by reference and may be modified by the callback function.

Returns the EventObject or false (if not dispatched).

Event::dispatch($eventName [,$arguments])

Fires/dispatches an event

$eventName is the name of the event to fire.

$arguments is/are any additional values that are passed to the listener callback(s). These values are passed as arguments to the callback function/method and in the $event->args property by reference and may be modified by the callback function.

Returns the EventObject.

Event::alias($aliasName, $eventName)

Creates an alias to an event for listeners.
An alias must be created before an event is fired. Only the original event can be fired (not the alias). Listeners can listen to either the event name or the event alias. Note however that all $aliasName listeners are fired after all $eventName listeners.

$aliasName is the alias of $eventName.

$eventName is the name of an event to be fired.

Returns nothing.

Event::wasFired($eventName)

Was an event already fired?

$eventName is the name of the event.

Returns true if the event was previously fired, otherwise false.

Event::hasListeners($eventName)

Does an event have registered listeners?

$eventName is the name of the event.

Returns true if the event has listeners, otherwise false.

Listener callbacks are executed in the order in which they were added through Event::listen(). If a callback returns a value of false or calls the $event->stop() method, event propagation stops and no further listeners are called.

Similarly, the $event->listener->stop() method will stop an event listener from listening for future events (identical to Event::ignore($event->listener)).

The callback functions receive all of the arguments passed to the Event::fire() method. Additionally, the last argument passed to the callback is the event object (EventObject type), the properties of which are:

$event->name (string) the event name
$event->args (array) values passed to Event::fire() (by reference)
$event->listener (object) the current listener object (can be used by Event::ignore())

Since $event->args is an array passed by reference, changes to any of the values are passed on to any proceeding listeners and returned to the Event::fire() caller.

The EventObject is created once by the Event::dispatch() method and the same object is passed to all listeners. This allows for referencial treatment of arguments. The object is returned from Event::dispatch() so that the caller may obtain the updated values from the listeners.
i.e. $event = Event::fire('test:event','arg1'); // $event->args[0] ('arg1') may be updated by the listeners.

Example:

See eac_events.test.php for several examples and tests.