123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224
  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. /**
  49. * @var array contains all globally registered event handlers.
  50. */
  51. private static $_events = [];
  52. /**
  53. * Attaches an event handler to a class-level event.
  54. *
  55. * When a class-level event is triggered, event handlers attached
  56. * to that class and all parent classes will be invoked.
  57. *
  58. * For example, the following code attaches an event handler to `ActiveRecord`'s
  59. * `afterInsert` event:
  60. *
  61. * ```php
  62. * Event::on(ActiveRecord::className(), ActiveRecord::EVENT_AFTER_INSERT, function ($event) {
  63. * Yii::trace(get_class($event->sender) . ' is inserted.');
  64. * });
  65. * ```
  66. *
  67. * The handler will be invoked for EVERY successful ActiveRecord insertion.
  68. *
  69. * For more details about how to declare an event handler, please refer to [[Component::on()]].
  70. *
  71. * @param string $class the fully qualified class name to which the event handler needs to attach.
  72. * @param string $name the event name.
  73. * @param callable $handler the event handler.
  74. * @param mixed $data the data to be passed to the event handler when the event is triggered.
  75. * When the event handler is invoked, this data can be accessed via [[Event::data]].
  76. * @param boolean $append whether to append new event handler to the end of the existing
  77. * handler list. If `false`, the new handler will be inserted at the beginning of the existing
  78. * handler list.
  79. * @see off()
  80. */
  81. public static function on($class, $name, $handler, $data = null, $append = true)
  82. {
  83. $class = ltrim($class, '\\');
  84. if ($append || empty(self::$_events[$name][$class])) {
  85. self::$_events[$name][$class][] = [$handler, $data];
  86. } else {
  87. array_unshift(self::$_events[$name][$class], [$handler, $data]);
  88. }
  89. }
  90. /**
  91. * Detaches an event handler from a class-level event.
  92. *
  93. * This method is the opposite of [[on()]].
  94. *
  95. * @param string $class the fully qualified class name from which the event handler needs to be detached.
  96. * @param string $name the event name.
  97. * @param callable $handler the event handler to be removed.
  98. * If it is `null`, all handlers attached to the named event will be removed.
  99. * @return boolean whether a handler is found and detached.
  100. * @see on()
  101. */
  102. public static function off($class, $name, $handler = null)
  103. {
  104. $class = ltrim($class, '\\');
  105. if (empty(self::$_events[$name][$class])) {
  106. return false;
  107. }
  108. if ($handler === null) {
  109. unset(self::$_events[$name][$class]);
  110. return true;
  111. } else {
  112. $removed = false;
  113. foreach (self::$_events[$name][$class] as $i => $event) {
  114. if ($event[0] === $handler) {
  115. unset(self::$_events[$name][$class][$i]);
  116. $removed = true;
  117. }
  118. }
  119. if ($removed) {
  120. self::$_events[$name][$class] = array_values(self::$_events[$name][$class]);
  121. }
  122. return $removed;
  123. }
  124. }
  125. /**
  126. * Detaches all registered class-level event handlers.
  127. * @see on()
  128. * @see off()
  129. * @since 2.0.10
  130. */
  131. public static function offAll()
  132. {
  133. self::$_events = [];
  134. }
  135. /**
  136. * Returns a value indicating whether there is any handler attached to the specified class-level event.
  137. * Note that this method will also check all parent classes to see if there is any handler attached
  138. * to the named event.
  139. * @param string|object $class the object or the fully qualified class name specifying the class-level event.
  140. * @param string $name the event name.
  141. * @return boolean whether there is any handler attached to the event.
  142. */
  143. public static function hasHandlers($class, $name)
  144. {
  145. if (empty(self::$_events[$name])) {
  146. return false;
  147. }
  148. if (is_object($class)) {
  149. $class = get_class($class);
  150. } else {
  151. $class = ltrim($class, '\\');
  152. }
  153. $classes = array_merge(
  154. [$class],
  155. class_parents($class, true),
  156. class_implements($class, true)
  157. );
  158. foreach ($classes as $class) {
  159. if (!empty(self::$_events[$name][$class])) {
  160. return true;
  161. }
  162. }
  163. return false;
  164. }
  165. /**
  166. * Triggers a class-level event.
  167. * This method will cause invocation of event handlers that are attached to the named event
  168. * for the specified class and all its parent classes.
  169. * @param string|object $class the object or the fully qualified class name specifying the class-level event.
  170. * @param string $name the event name.
  171. * @param Event $event the event parameter. If not set, a default [[Event]] object will be created.
  172. */
  173. public static function trigger($class, $name, $event = null)
  174. {
  175. if (empty(self::$_events[$name])) {
  176. return;
  177. }
  178. if ($event === null) {
  179. $event = new static;
  180. }
  181. $event->handled = false;
  182. $event->name = $name;
  183. if (is_object($class)) {
  184. if ($event->sender === null) {
  185. $event->sender = $class;
  186. }
  187. $class = get_class($class);
  188. } else {
  189. $class = ltrim($class, '\\');
  190. }
  191. $classes = array_merge(
  192. [$class],
  193. class_parents($class, true),
  194. class_implements($class, true)
  195. );
  196. foreach ($classes as $class) {
  197. if (!empty(self::$_events[$name][$class])) {
  198. foreach (self::$_events[$name][$class] as $handler) {
  199. $event->data = $handler[1];
  200. call_user_func($handler[0], $event);
  201. if ($event->handled) {
  202. return;
  203. }
  204. }
  205. }
  206. }
  207. }
  208. }