478 lines
17 KiB
PHP
478 lines
17 KiB
PHP
|
<?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 284686 2009-07-24 05:22:17Z clockwerx $
|
||
|
|
|
||
|
|
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: @package_version@
|
||
|
|
* @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;
|
||
|
|
}
|
||
|
|
|
||
|
|
}
|
||
|
|
?>
|