PHP Class Event_Dispatcher

The Event_Dispatcher acts acts as a notification dispatch table. It is used to notify other objects of interesting things, if they meet certain criteria. This information is encapsulated in {@link Event_Notification} objects. Client objects register themselves with the Event_Dispatcher as observers of specific notifications posted by other objects. When an event occurs, an object posts an appropriate notification to the Event_Dispatcher. The Event_Dispatcher dispatches a message to each registered observer, passing the notification as the sole argument. The Event_Dispatcher is actually a combination of three design patterns: the Singleton, {@link http://c2.com/cgi/wiki?MediatorPattern Mediator}, and Observer patterns. The idea behind Event_Dispatcher is borrowed from {@link http://developer.apple.com/documentation/Cocoa/Conceptual/Notifications/index.html Apple's Cocoa framework}.

See link: http://pear.php.net/package/Event_Dispatcher

Author: Bertrand Mansion ([email protected])

Author: Stephan Schmidt ([email protected])

Show file Open project: sourcefabric/newscoop Class Usage Examples

Public Properties

Property	Type	Description
$_name	string	Name of the dispatcher
$_nestedDispatchers	array	Nested observers
$_notificationClass	string	Class used for notifications
$_pending	array	Pending notifications
$_ro	array	Registered observer callbacks

Public Methods

Method	Description
Event_Dispatcher ( $name )	PHP4 constructor
__construct ( $name )	PHP5 constructor
addNestedDispatcher ( &$dispatcher )	add a new nested dispatcher
addObserver ( $callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = null ) : void	Registers an observer callback
getInstance ( $name = '__default' ) : object	Returns a notification dispatcher singleton
getName ( ) : string	Get the name of the dispatcher.
getObservers ( $nName = EVENT_DISPATCHER_GLOBAL, $class = null ) : array	Get all observers, that have been registered for a notification
observerRegistered ( $callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = null ) : boolean	Check, whether the specified observer has been registered with the dispatcher
post ( &$object, $nName, $info = [], $pending = true, $bubble = true ) : object	Creates and posts a notification object
postNotification ( &$notification, $pending = true, $bubble = true ) : object	Posts the {@link Event_Notification} object
removeNestedDispatcher ( $dispatcher ) : boolean	remove a nested dispatcher
removeObserver ( $callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = null ) : boolean	Removes a registered observer that correspond to the given criteria
setNotificationClass ( $class ) : boolean	Changes the class used for notifications

Method Details

Event_Dispatcher() public method

Please use {@link getInstance()} instead.

public Event_Dispatcher ( $name )

__construct() public method

Please use {@link getInstance()} instead.

public __construct ( $name )

addNestedDispatcher() public method

Notifications will be broadcasted to this dispatcher as well, which allows you to create event bubbling.

public addNestedDispatcher ( &$dispatcher )

addObserver() public method

This method registers a {@link http://www.php.net/manual/en/language.pseudo-types.php#language.types.callback callback} which is called when the notification corresponding to the criteria given at registration time is posted. The criteria are the notification name and eventually the class of the object posted with the notification. If there are any pending notifications corresponding to the criteria given here, the callback will be called straight away. If the notification name is empty, the observer will receive all the posted notifications. Same goes for the class name.

public addObserver ( $callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = null ) : void
return	void

getInstance() public method

There is usually no need to have more than one notification center for an application so this is the recommended way to get a Event_Dispatcher object.

public getInstance ( $name = '__default' ) : object
return	object	Event_Dispatcher

getName() public method

The name is the unique identifier of a dispatcher.

public getName ( ) : string
return	string	name of the dispatcher

getObservers() public method

Get all observers, that have been registered for a notification

public getObservers ( $nName = EVENT_DISPATCHER_GLOBAL, $class = null ) : array
return	array	List of all observers

observerRegistered() public method

Check, whether the specified observer has been registered with the dispatcher

public observerRegistered ( $callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = null ) : boolean
return	boolean	True if the observer has been registered, false otherwise

post() public method

The purpose of the optional associated object is generally to pass the object posting the notification to the observers, so that the observers can query the posting object for more information about the event. Notifications are by default added to a pending notification list. This way, if an observer is not registered by the time they are posted, it will still be notified when it is added as an observer. This behaviour can be turned off in order to make sure that only the registered observers will be notified. The info array serves as a container for any kind of useful information. It is added to the notification object and posted along.

public post ( &$object, $nName, $info = [], $pending = true, $bubble = true ) : object
return	object	The notification object

postNotification() public method

Posts the {@link Event_Notification} object

removeNestedDispatcher() public method

remove a nested dispatcher

public removeNestedDispatcher ( $dispatcher ) : boolean
return	boolean

removeObserver() public method

Removes a registered observer that correspond to the given criteria

public removeObserver ( $callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = null ) : boolean
return	boolean	True if an observer was removed, false otherwise

setNotificationClass() public method

You may call this method on an object to change it for a single dispatcher or statically, to set the default for all dispatchers that will be created.

public setNotificationClass ( $class ) : boolean
return	boolean

Property Details

$_name public property

Name of the dispatcher

public string $_name
return	string

$_nestedDispatchers public property

Nested observers

public array $_nestedDispatchers
return	array

$_notificationClass public property

Class used for notifications

public string $_notificationClass
return	string

$_pending public property

Pending notifications

public array $_pending
return	array

$_ro public property

Registered observer callbacks

public array $_ro
return	array

public postNotification ( &$notification, $pending = true, $bubble = true ) : object
return	object	The notification object