You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

197 lines
7.1KB

  1. <?php
  2. /**
  3. * @link http://www.yiiframework.com/
  4. * @copyright Copyright (c) 2008 Yii Software LLC
  5. * @license http://www.yiiframework.com/license/
  6. */
  7. namespace yii\base;
  8. /**
  9. * Event is the base class for all event classes.
  10. *
  11. * It encapsulates the parameters associated with an event.
  12. * The [[sender]] property describes who raises the event.
  13. * And the [[handled]] property indicates if the event is handled.
  14. * If an event handler sets [[handled]] to be true, the rest of the
  15. * uninvoked handlers will no longer be called to handle the event.
  16. *
  17. * Additionally, when attaching an event handler, extra data may be passed
  18. * and be available via the [[data]] property when the event handler is invoked.
  19. *
  20. * @author Qiang Xue <qiang.xue@gmail.com>
  21. * @since 2.0
  22. */
  23. class Event extends Object
  24. {
  25. /**
  26. * @var string the event name. This property is set by [[Component::trigger()]] and [[trigger()]].
  27. * Event handlers may use this property to check what event it is handling.
  28. */
  29. public $name;
  30. /**
  31. * @var object the sender of this event. If not set, this property will be
  32. * set as the object whose "trigger()" method is called.
  33. * This property may also be a `null` when this event is a
  34. * class-level event which is triggered in a static context.
  35. */
  36. public $sender;
  37. /**
  38. * @var boolean whether the event is handled. Defaults to false.
  39. * When a handler sets this to be true, the event processing will stop and
  40. * ignore the rest of the uninvoked event handlers.
  41. */
  42. public $handled = false;
  43. /**
  44. * @var mixed the data that is passed to [[Component::on()]] when attaching an event handler.
  45. * Note that this varies according to which event handler is currently executing.
  46. */
  47. public $data;
  48. private static $_events = [];
  49. /**
  50. * Attaches an event handler to a class-level event.
  51. *
  52. * When a class-level event is triggered, event handlers attached
  53. * to that class and all parent classes will be invoked.
  54. *
  55. * For example, the following code attaches an event handler to `ActiveRecord`'s
  56. * `afterInsert` event:
  57. *
  58. * ~~~
  59. * Event::on(ActiveRecord::className(), ActiveRecord::EVENT_AFTER_INSERT, function ($event) {
  60. * Yii::trace(get_class($event->sender) . ' is inserted.');
  61. * });
  62. * ~~~
  63. *
  64. * The handler will be invoked for EVERY successful ActiveRecord insertion.
  65. *
  66. * For more details about how to declare an event handler, please refer to [[Component::on()]].
  67. *
  68. * @param string $class the fully qualified class name to which the event handler needs to attach.
  69. * @param string $name the event name.
  70. * @param callable $handler the event handler.
  71. * @param mixed $data the data to be passed to the event handler when the event is triggered.
  72. * When the event handler is invoked, this data can be accessed via [[Event::data]].
  73. * @param boolean $append whether to append new event handler to the end of the existing
  74. * handler list. If false, the new handler will be inserted at the beginning of the existing
  75. * handler list.
  76. * @see off()
  77. */
  78. public static function on($class, $name, $handler, $data = null, $append = true)
  79. {
  80. $class = ltrim($class, '\\');
  81. if ($append || empty(self::$_events[$name][$class])) {
  82. self::$_events[$name][$class][] = [$handler, $data];
  83. } else {
  84. array_unshift(self::$_events[$name][$class], [$handler, $data]);
  85. }
  86. }
  87. /**
  88. * Detaches an event handler from a class-level event.
  89. *
  90. * This method is the opposite of [[on()]].
  91. *
  92. * @param string $class the fully qualified class name from which the event handler needs to be detached.
  93. * @param string $name the event name.
  94. * @param callable $handler the event handler to be removed.
  95. * If it is null, all handlers attached to the named event will be removed.
  96. * @return boolean whether a handler is found and detached.
  97. * @see on()
  98. */
  99. public static function off($class, $name, $handler = null)
  100. {
  101. $class = ltrim($class, '\\');
  102. if (empty(self::$_events[$name][$class])) {
  103. return false;
  104. }
  105. if ($handler === null) {
  106. unset(self::$_events[$name][$class]);
  107. return true;
  108. } else {
  109. $removed = false;
  110. foreach (self::$_events[$name][$class] as $i => $event) {
  111. if ($event[0] === $handler) {
  112. unset(self::$_events[$name][$class][$i]);
  113. $removed = true;
  114. }
  115. }
  116. if ($removed) {
  117. self::$_events[$name][$class] = array_values(self::$_events[$name][$class]);
  118. }
  119. return $removed;
  120. }
  121. }
  122. /**
  123. * Returns a value indicating whether there is any handler attached to the specified class-level event.
  124. * Note that this method will also check all parent classes to see if there is any handler attached
  125. * to the named event.
  126. * @param string|object $class the object or the fully qualified class name specifying the class-level event.
  127. * @param string $name the event name.
  128. * @return boolean whether there is any handler attached to the event.
  129. */
  130. public static function hasHandlers($class, $name)
  131. {
  132. if (empty(self::$_events[$name])) {
  133. return false;
  134. }
  135. if (is_object($class)) {
  136. $class = get_class($class);
  137. } else {
  138. $class = ltrim($class, '\\');
  139. }
  140. do {
  141. if (!empty(self::$_events[$name][$class])) {
  142. return true;
  143. }
  144. } while (($class = get_parent_class($class)) !== false);
  145. return false;
  146. }
  147. /**
  148. * Triggers a class-level event.
  149. * This method will cause invocation of event handlers that are attached to the named event
  150. * for the specified class and all its parent classes.
  151. * @param string|object $class the object or the fully qualified class name specifying the class-level event.
  152. * @param string $name the event name.
  153. * @param Event $event the event parameter. If not set, a default [[Event]] object will be created.
  154. */
  155. public static function trigger($class, $name, $event = null)
  156. {
  157. if (empty(self::$_events[$name])) {
  158. return;
  159. }
  160. if ($event === null) {
  161. $event = new static;
  162. }
  163. $event->handled = false;
  164. $event->name = $name;
  165. if (is_object($class)) {
  166. if ($event->sender === null) {
  167. $event->sender = $class;
  168. }
  169. $class = get_class($class);
  170. } else {
  171. $class = ltrim($class, '\\');
  172. }
  173. do {
  174. if (!empty(self::$_events[$name][$class])) {
  175. foreach (self::$_events[$name][$class] as $handler) {
  176. $event->data = $handler[1];
  177. call_user_func($handler[0], $event);
  178. if ($event->handled) {
  179. return;
  180. }
  181. }
  182. }
  183. } while (($class = get_parent_class($class)) !== false);
  184. }
  185. }