Subversion Repositories SmartDukaan

<?php

/**

 * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)

 * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)

 *

 * Licensed under The MIT License

 * For full copyright and license information, please see the LICENSE.txt

 * Redistributions of files must retain the above copyright notice.

 *

 * @copyright	  Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)

 * @link		  http://cakephp.org CakePHP(tm) Project

 * @package		  Cake.Event

 * @since		  CakePHP(tm) v 2.1

 * @license       http://www.opensource.org/licenses/mit-license.php MIT License

 */

App::uses('CakeEventListener', 'Event');

/**

 * The event manager is responsible for keeping track of event listeners, passing the correct

 * data to them, and firing them in the correct order, when associated events are triggered. You

 * can create multiple instances of this object to manage local events or keep a single instance

 * and pass it around to manage all events in your app.

 *

 * @package Cake.Event

 */

class CakeEventManager {

/**

 * The default priority queue value for new, attached listeners

 *

 * @var int

 */

	public static $defaultPriority = 10;

/**

 * The globally available instance, used for dispatching events attached from any scope

 *

 * @var CakeEventManager

 */

	protected static $_generalManager = null;

/**

 * List of listener callbacks associated to

 *

 * @var object

 */

	protected $_listeners = array();

/**

 * Internal flag to distinguish a common manager from the singleton

 *

 * @var bool

 */

	protected $_isGlobal = false;

/**

 * Returns the globally available instance of a CakeEventManager

 * this is used for dispatching events attached from outside the scope

 * other managers were created. Usually for creating hook systems or inter-class

 * communication

 *

 * If called with the first parameter, it will be set as the globally available instance

 *

 * @param CakeEventManager $manager Optional event manager instance.

 * @return CakeEventManager the global event manager

 */

	public static function instance($manager = null) {

		if ($manager instanceof CakeEventManager) {

			static::$_generalManager = $manager;

		}

		if (empty(static::$_generalManager)) {

			static::$_generalManager = new CakeEventManager();

		}

		static::$_generalManager->_isGlobal = true;

		return static::$_generalManager;

	}

/**

 * Adds a new listener to an event. Listeners

 *

 * @param callback|CakeEventListener $callable PHP valid callback type or instance of CakeEventListener to be called

 * when the event named with $eventKey is triggered. If a CakeEventListener instance is passed, then the `implementedEvents`

 * method will be called on the object to register the declared events individually as methods to be managed by this class.

 * It is possible to define multiple event handlers per event name.

 *

 * @param string $eventKey The event unique identifier name with which the callback will be associated. If $callable

 * is an instance of CakeEventListener this argument will be ignored

 *

 * @param array $options used to set the `priority` and `passParams` flags to the listener.

 * Priorities are handled like queues, and multiple attachments added to the same priority queue will be treated in

 * the order of insertion. `passParams` means that the event data property will be converted to function arguments

 * when the listener is called. If $called is an instance of CakeEventListener, this parameter will be ignored

 *

 * @return void

 * @throws InvalidArgumentException When event key is missing or callable is not an

 *   instance of CakeEventListener.

 */

	public function attach($callable, $eventKey = null, $options = array()) {

		if (!$eventKey && !($callable instanceof CakeEventListener)) {

			throw new InvalidArgumentException(__d('cake_dev', 'The eventKey variable is required'));

		}

		if ($callable instanceof CakeEventListener) {

			$this->_attachSubscriber($callable);

			return;

		}

		$options = $options + array('priority' => static::$defaultPriority, 'passParams' => false);

		$this->_listeners[$eventKey][$options['priority']][] = array(

			'callable' => $callable,

			'passParams' => $options['passParams'],

		);

	}

/**

 * Auxiliary function to attach all implemented callbacks of a CakeEventListener class instance

 * as individual methods on this manager

 *

 * @param CakeEventListener $subscriber Event listener.

 * @return void

 */

	protected function _attachSubscriber(CakeEventListener $subscriber) {

		foreach ((array)$subscriber->implementedEvents() as $eventKey => $function) {

			$options = array();

			$method = $function;

			if (is_array($function) && isset($function['callable'])) {

				list($method, $options) = $this->_extractCallable($function, $subscriber);

			} elseif (is_array($function) && is_numeric(key($function))) {

				foreach ($function as $f) {

					list($method, $options) = $this->_extractCallable($f, $subscriber);

					$this->attach($method, $eventKey, $options);

				}

				continue;

			}

			if (is_string($method)) {

				$method = array($subscriber, $function);

			}

			$this->attach($method, $eventKey, $options);

		}

	}

/**

 * Auxiliary function to extract and return a PHP callback type out of the callable definition

 * from the return value of the `implementedEvents` method on a CakeEventListener

 *

 * @param array $function the array taken from a handler definition for an event

 * @param CakeEventListener $object The handler object

 * @return callback

 */

	protected function _extractCallable($function, $object) {

		$method = $function['callable'];

		$options = $function;

		unset($options['callable']);

		if (is_string($method)) {

			$method = array($object, $method);

		}

		return array($method, $options);

	}

/**

 * Removes a listener from the active listeners.

 *

 * @param callback|CakeEventListener $callable any valid PHP callback type or an instance of CakeEventListener

 * @param string $eventKey The event unique identifier name with which the callback has been associated

 * @return void

 */

	public function detach($callable, $eventKey = null) {

		if ($callable instanceof CakeEventListener) {

			return $this->_detachSubscriber($callable, $eventKey);

		}

		if (empty($eventKey)) {

			foreach (array_keys($this->_listeners) as $eventKey) {

				$this->detach($callable, $eventKey);

			}

			return;

		}

		if (empty($this->_listeners[$eventKey])) {

			return;

		}

		foreach ($this->_listeners[$eventKey] as $priority => $callables) {

			foreach ($callables as $k => $callback) {

				if ($callback['callable'] === $callable) {

					unset($this->_listeners[$eventKey][$priority][$k]);

					break;

				}

			}

		}

	}

/**

 * Auxiliary function to help detach all listeners provided by an object implementing CakeEventListener

 *

 * @param CakeEventListener $subscriber the subscriber to be detached

 * @param string $eventKey optional event key name to unsubscribe the listener from

 * @return void

 */

	protected function _detachSubscriber(CakeEventListener $subscriber, $eventKey = null) {

		$events = (array)$subscriber->implementedEvents();

		if (!empty($eventKey) && empty($events[$eventKey])) {

			return;

		} elseif (!empty($eventKey)) {

			$events = array($eventKey => $events[$eventKey]);

		}

		foreach ($events as $key => $function) {

			if (is_array($function)) {

				if (is_numeric(key($function))) {

					foreach ($function as $handler) {

						$handler = isset($handler['callable']) ? $handler['callable'] : $handler;

						$this->detach(array($subscriber, $handler), $key);

					}

					continue;

				}

				$function = $function['callable'];

			}

			$this->detach(array($subscriber, $function), $key);

		}

	}

/**

 * Dispatches a new event to all configured listeners

 *

 * @param string|CakeEvent $event the event key name or instance of CakeEvent

 * @return CakeEvent

 * @triggers $event

 */

	public function dispatch($event) {

		if (is_string($event)) {

			$event = new CakeEvent($event);

		}

		$listeners = $this->listeners($event->name());

		if (empty($listeners)) {

			return $event;

		}

		foreach ($listeners as $listener) {

			if ($event->isStopped()) {

				break;

			}

			if ($listener['passParams'] === true) {

				$result = call_user_func_array($listener['callable'], $event->data);

			} else {

				$result = call_user_func($listener['callable'], $event);

			}

			if ($result === false) {

				$event->stopPropagation();

			}

			if ($result !== null) {

				$event->result = $result;

			}

		}

		return $event;

	}

/**

 * Returns a list of all listeners for an eventKey in the order they should be called

 *

 * @param string $eventKey Event key.

 * @return array

 */

	public function listeners($eventKey) {

		$localListeners = array();

		$priorities = array();

		if (!$this->_isGlobal) {

			$localListeners = $this->prioritisedListeners($eventKey);

			$localListeners = empty($localListeners) ? array() : $localListeners;

		}

		$globalListeners = static::instance()->prioritisedListeners($eventKey);

		$globalListeners = empty($globalListeners) ? array() : $globalListeners;

		$priorities = array_merge(array_keys($globalListeners), array_keys($localListeners));

		$priorities = array_unique($priorities);

		asort($priorities);

		$result = array();

		foreach ($priorities as $priority) {

			if (isset($globalListeners[$priority])) {

				$result = array_merge($result, $globalListeners[$priority]);

			}

			if (isset($localListeners[$priority])) {

				$result = array_merge($result, $localListeners[$priority]);

			}

		}

		return $result;

	}

/**

 * Returns the listeners for the specified event key indexed by priority

 *

 * @param string $eventKey Event key.

 * @return array

 */

	public function prioritisedListeners($eventKey) {

		if (empty($this->_listeners[$eventKey])) {

			return array();

		}

		return $this->_listeners[$eventKey];

	}

}