Viewing file:  Dispatcher.php (17 KB) -rw-rw-rw-
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
<?php
// +-----------------------------------------------------------------------+
// | Copyright (c) 2005, Bertrand Mansion |
// | All rights reserved. |
// | |
// | Redistribution and use in source and binary forms, with or without |
// | modification, are permitted provided that the following conditions |
// | are met: |
// | |
// | o Redistributions of source code must retain the above copyright |
// | notice, this list of conditions and the following disclaimer. |
// | o Redistributions in binary form must reproduce the above copyright |
// | notice, this list of conditions and the following disclaimer in the |
// | documentation and/or other materials provided with the distribution.|
// | o The names of the authors may not be used to endorse or promote |
// | products derived from this software without specific prior written |
// | permission. |
// | |
// | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
// | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
// | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
// | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
// | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
// | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
// | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
// | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
// | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
// | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
// | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
// | |
// +-----------------------------------------------------------------------+
// | Author: Bertrand Mansion <bmansion@mamasam.com> |
// | Stephan Schmidt <schst@php.net> |
// +-----------------------------------------------------------------------+
//
// $Id: Dispatcher.php,v 1.4 2005/09/22 15:37:10 schst Exp $
require_once 'Event/Notification.php';
/**
* Pseudo 'static property' for Notification object
* @global array $GLOBALS["_Event_Dispatcher"]
*/
$GLOBALS['_Event_Dispatcher'] = array(
'NotificationClass' => 'Event_Notification'
);
/**
* Registers a global observer
*/
define('EVENT_DISPATCHER_GLOBAL', '');
/**
* Dispatch notifications using PHP callbacks
*
* 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}.
*
* @category Event
* @package Event_Dispatcher
* @author Bertrand Mansion <bmansion@mamasam.com>
* @author Stephan Schmidt <schst@php.net>
* @copyright 1997-2005 The PHP Group
* @license http://www.opensource.org/licenses/bsd-license.php BSD License
* @version Release: 1.0.0
* @link http://pear.php.net/package/Event_Dispatcher
*/
class Event_Dispatcher
{
/**
* Registered observer callbacks
* @var array
* @access private
*/
var $_ro = array();
/**
* Pending notifications
* @var array
* @access private
*/
var $_pending = array();
/**
* Nested observers
* @var array
* @access private
*/
var $_nestedDispatchers = array();
/**
* Name of the dispatcher
* @var string
* @access private
*/
var $_name = null;
/**
* Class used for notifications
* @var string
* @access private
*/
var $_notificationClass = null;
/**
* PHP4 constructor
*
* Please use {@link getInstance()} instead.
*
* @access private
* @param string Name of the notification dispatcher.
*/
function Event_Dispatcher($name)
{
Event_Dispatcher::__construct($name);
}
/**
* PHP5 constructor
*
* Please use {@link getInstance()} instead.
*
* @access private
* @param string Name of the notification dispatcher.
*/
function __construct($name)
{
$this->_name = $name;
$this->_notificationClass = $GLOBALS['_Event_Dispatcher']['NotificationClass'];
}
/**
* Returns a notification dispatcher singleton
*
* 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.
*
* @param string Name of the notification dispatcher.
* The default notification dispatcher is named __default.
*
* @return object Event_Dispatcher
*/
function &getInstance($name = '__default')
{
static $dispatchers = array();
if (!isset($dispatchers[$name])) {
$dispatchers[$name] = new Event_Dispatcher($name);
}
return $dispatchers[$name];
}
/**
* Registers an observer callback
*
* 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.
*
* @access public
* @param mixed A PHP callback
* @param string Expected notification name, serves as a filter
* @param string Expected contained object class, serves as a filter
* @return void
*/
function addObserver($callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = null)
{
if (is_array($callback)) {
if (is_object($callback[0])) {
// Note : PHP4 does not allow correct object comparison so
// only the class name is used for registration checks.
$reg = get_class($callback[0]).'::'.$callback[1];
} else {
$reg = $callback[0].'::'.$callback[1];
}
} else {
$reg = $callback;
}
$this->_ro[$nName][$reg] = array(
'callback' => $callback,
'class' => $class
);
// Post eventual pending notifications for this observer
if (isset($this->_pending[$nName])) {
foreach (array_keys($this->_pending[$nName]) as $k) {
$notification =& $this->_pending[$nName][$k];
if (!$notification->isNotificationCancelled()) {
$objClass = get_class($notification->getNotificationObject());
if (empty($class) || strcasecmp($class, $objClass) == 0) {
call_user_func_array($callback, array(&$notification));
$notification->increaseNotificationCount();
}
}
}
}
}
/**
* Creates and posts a notification object
*
* 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.
*
* @access public
* @param object Notification associated object
* @param string Notification name
* @param array Optional user information
* @param bool Whether the notification is pending
* @param bool Whether you want the notification to bubble up
* @return object The notification object
*/
function &post(&$object, $nName, $info = array(), $pending = true, $bubble = true)
{
$notification =& new $this->_notificationClass($object, $nName, $info);
return $this->postNotification($notification, $pending, $bubble);
}
/**
* Posts the {@link Event_Notification} object
*
* @access public
* @param object The Notification object
* @param bool Whether to post the notification immediately
* @param bool Whether you want the notification to bubble up
* @see Event_Dispatcher::post()
* @return object The notification object
*/
function &postNotification(&$notification, $pending = true, $bubble = true)
{
$nName = $notification->getNotificationName();
if ($pending === true) {
$this->_pending[$nName][] =& $notification;
}
$objClass = get_class($notification->getNotificationObject());
// Find the registered observers
if (isset($this->_ro[$nName])) {
foreach (array_keys($this->_ro[$nName]) as $k) {
$rObserver =& $this->_ro[$nName][$k];
if ($notification->isNotificationCancelled()) {
return $notification;
}
if (empty($rObserver['class']) ||
strcasecmp($rObserver['class'], $objClass) == 0) {
call_user_func_array($rObserver['callback'], array(&$notification));
$notification->increaseNotificationCount();
}
}
}
// Notify globally registered observers
if (isset($this->_ro[EVENT_DISPATCHER_GLOBAL])) {
foreach (array_keys($this->_ro[EVENT_DISPATCHER_GLOBAL]) as $k) {
$rObserver =& $this->_ro[EVENT_DISPATCHER_GLOBAL][$k];
if ($notification->isNotificationCancelled()) {
return $notification;
}
if (empty($rObserver['class']) ||
strcasecmp($rObserver['class'], $objClass) == 0) {
call_user_func_array($rObserver['callback'], array(&$notification));
$notification->increaseNotificationCount();
}
}
}
if ($bubble === false) {
return $notification;
}
// Notify in nested dispatchers
foreach (array_keys($this->_nestedDispatchers) as $nested) {
$notification =& $this->_nestedDispatchers[$nested]->postNotification($notification, $pending);
}
return $notification;
}
/**
* Removes a registered observer that correspond to the given criteria
*
* @access public
* @param mixed A PHP callback
* @param string Notification name
* @param string Contained object class
* @return bool True if an observer was removed, false otherwise
*/
function removeObserver($callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = null)
{
if (is_array($callback)) {
if (is_object($callback[0])) {
$reg = get_class($callback[0]).'::'.$callback[1];
} else {
$reg = $callback[0].'::'.$callback[1];
}
} else {
$reg = $callback;
}
$removed = false;
if (isset($this->_ro[$nName][$reg])) {
if (!empty($class)) {
if (strcasecmp($this->_ro[$nName][$reg]['class'], $class) == 0) {
unset($this->_ro[$nName][$reg]);
$removed = true;
}
} else {
unset($this->_ro[$nName][$reg]);
$removed = true;
}
}
if (isset($this->_ro[$nName]) && count($this->_ro[$nName]) == 0) {
unset($this->_ro[$nName]);
}
return $removed;
}
/**
* Check, whether the specified observer has been registered with the
* dispatcher
*
* @access public
* @param mixed A PHP callback
* @param string Notification name
* @param string Contained object class
* @return bool True if the observer has been registered, false otherwise
*/
function observerRegistered($callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = null)
{
if (is_array($callback)) {
if (is_object($callback[0])) {
$reg = get_class($callback[0]).'::'.$callback[1];
} else {
$reg = $callback[0].'::'.$callback[1];
}
} else {
$reg = $callback;
}
if (!isset($this->_ro[$nName][$reg])) {
return false;
}
if (empty($class)) {
return true;
}
if (strcasecmp($this->_ro[$nName][$reg]['class'], $class) == 0) {
return true;
}
return false;
}
/**
* Get all observers, that have been registered for a notification
*
* @access public
* @param string Notification name
* @param string Contained object class
* @return array List of all observers
*/
function getObservers($nName = EVENT_DISPATCHER_GLOBAL, $class = null)
{
$observers = array();
if (!isset($this->_ro[$nName])) {
return $observers;
}
foreach ($this->_ro[$nName] as $reg => $observer) {
if ($class == null || $observer['class'] == null || strcasecmp($observer['class'], $class) == 0) {
$observers[] = $reg;
}
}
return $observers;
}
/**
* Get the name of the dispatcher.
*
* The name is the unique identifier of a dispatcher.
*
* @access public
* @return string name of the dispatcher
*/
function getName()
{
return $this->_name;
}
/**
* add a new nested dispatcher
*
* Notifications will be broadcasted to this dispatcher as well, which
* allows you to create event bubbling.
*
* @access public
* @param Event_Dispatcher The nested dispatcher
*/
function addNestedDispatcher(&$dispatcher)
{
$name = $dispatcher->getName();
$this->_nestedDispatchers[$name] =& $dispatcher;
}
/**
* remove a nested dispatcher
*
* @access public
* @param Event_Dispatcher Dispatcher to remove
* @return boolean
*/
function removeNestedDispatcher($dispatcher)
{
if (is_object($dispatcher)) {
$dispatcher = $dispatcher->getName();
}
if (!isset($this->_nestedDispatchers[$dispatcher])) {
return false;
}
unset($this->_nestedDispatchers[$dispatcher]);
return true;
}
/**
* Changes the class used for notifications
*
* 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.
*
* @access public
* @param string name of the notification class
* @return boolean
*/
function setNotificationClass($class)
{
if (isset($this) && is_a($this, 'Event_Dispatcher')) {
$this->_notificationClass = $class;
return true;
}
$GLOBALS['_Event_Dispatcher']['NotificationClass'] = $class;
return true;
}
}
?>
|