/lib/Cake/Event/CakeEventManager.php - アノテート - pictcode - Redmine

pictcode / lib / Cake / Event / CakeEventManager.php @ 0b1b8047

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