/lib/Cake/Event/CakeEventManager.php - pictcode - Redmine

pictcode / lib / Cake / Event / CakeEventManager.php @ 1368d528

       <?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];
+              }
+      }