Interoperable Package

[mbabker]

This is a refactoring of the event package for improved interoperability with the PHP community (based primarily on the Symfony Event Dispatcher as that appears to be the most widely used event system with others emulating it in some ways).

Major Changes

PHP 5.4 Dependency

The package typehints for callables, this is a PHP 5.4 feature.

Refactored DispatcherInterface

The most disruptive change is to the DispatcherInterface. The triggerEvent is removed from the interface (retained in the Dispatcher class) and the interface now composes of addListener, dispatch, and removeListener. The addListener and removeListener methods are refactored to adjust how listeners are managed; now an event name and a callable are required to be given to both methods (with addListener now supporting priorities by the method's signature instead of embedded into the old $events array).

Refactored Dispatcher

The dispatcher previously behaved as a combined event listener and subscriber (using Symfony logic) and would try to register all of a listener class' public methods as listeners for dispatched events. Now, methods must be explicitly registered through addListener. The refactored method requires the event name to be specified and the callable to be triggered when an event is dispatched. The Dispatcher class retains the current triggerEvent method, flagged as deprecated for 3.0, and proxies it into the now preferred dispatch method.

The getListenerPriority method signature is changed to require the event name and callable to check the priority for.

The hasListener method requires the first parameter to be the callable to check for existence, the second optional parameter is the event name to check if the callable is registered for.

The Dispatcher class continues support registration of Event objects to be dispatched for a given event name, and an internal method checks for this before using a base Event object.

DelegatingDispatcher class changes

The DelegatingDispatcher class is updated to implement all required interface changes.

Refactored EventInterface

The EventInterface adds two required methods for implementations of this interface: getArgument and stopPropagation. Events are now required to expose an API to retrieve event arguments (even if immutable) and implement a stopPropagation method to instruct the dispatcher to stop propagating the event.

Event class changes

The stop method in the Event class is deprecated in favor of the stopPropagation interface method. This method will be removed in 3.0.

Refactored ListenersPriorityQueue

The ListenersPriorityQueue class is refactored to use an internal storage array eliminating the SplPriorityQueue and SplObjectStorage storage mechanisms and the internals of this class are restructured for this change. For methods where the listener was an argument, these are now typehinted as callables similar to the Dispatcher the class is typically used with.

[wilsonge]

I like it :)