HasEvents.php 8.6KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355
  1. <?php
  2. namespace Illuminate\Database\Eloquent\Concerns;
  3. use Illuminate\Support\Arr;
  4. use Illuminate\Contracts\Events\Dispatcher;
  5. trait HasEvents
  6. {
  7. /**
  8. * The event map for the model.
  9. *
  10. * Allows for object-based events for native Eloquent events.
  11. *
  12. * @var array
  13. */
  14. protected $dispatchesEvents = [];
  15. /**
  16. * User exposed observable events.
  17. *
  18. * These are extra user-defined events observers may subscribe to.
  19. *
  20. * @var array
  21. */
  22. protected $observables = [];
  23. /**
  24. * Register observers with the model.
  25. *
  26. * @param object|array|string $classes
  27. * @return void
  28. */
  29. public static function observe($classes)
  30. {
  31. $instance = new static;
  32. foreach (Arr::wrap($classes) as $class) {
  33. $instance->registerObserver($class);
  34. }
  35. }
  36. /**
  37. * Register a single observer with the model.
  38. *
  39. * @param object|string $class
  40. * @return void
  41. */
  42. protected function registerObserver($class)
  43. {
  44. $className = is_string($class) ? $class : get_class($class);
  45. // When registering a model observer, we will spin through the possible events
  46. // and determine if this observer has that method. If it does, we will hook
  47. // it into the model's event system, making it convenient to watch these.
  48. foreach ($this->getObservableEvents() as $event) {
  49. if (method_exists($class, $event)) {
  50. static::registerModelEvent($event, $className.'@'.$event);
  51. }
  52. }
  53. }
  54. /**
  55. * Get the observable event names.
  56. *
  57. * @return array
  58. */
  59. public function getObservableEvents()
  60. {
  61. return array_merge(
  62. [
  63. 'retrieved', 'creating', 'created', 'updating', 'updated',
  64. 'saving', 'saved', 'restoring', 'restored',
  65. 'deleting', 'deleted', 'forceDeleted',
  66. ],
  67. $this->observables
  68. );
  69. }
  70. /**
  71. * Set the observable event names.
  72. *
  73. * @param array $observables
  74. * @return $this
  75. */
  76. public function setObservableEvents(array $observables)
  77. {
  78. $this->observables = $observables;
  79. return $this;
  80. }
  81. /**
  82. * Add an observable event name.
  83. *
  84. * @param array|mixed $observables
  85. * @return void
  86. */
  87. public function addObservableEvents($observables)
  88. {
  89. $this->observables = array_unique(array_merge(
  90. $this->observables, is_array($observables) ? $observables : func_get_args()
  91. ));
  92. }
  93. /**
  94. * Remove an observable event name.
  95. *
  96. * @param array|mixed $observables
  97. * @return void
  98. */
  99. public function removeObservableEvents($observables)
  100. {
  101. $this->observables = array_diff(
  102. $this->observables, is_array($observables) ? $observables : func_get_args()
  103. );
  104. }
  105. /**
  106. * Register a model event with the dispatcher.
  107. *
  108. * @param string $event
  109. * @param \Closure|string $callback
  110. * @return void
  111. */
  112. protected static function registerModelEvent($event, $callback)
  113. {
  114. if (isset(static::$dispatcher)) {
  115. $name = static::class;
  116. static::$dispatcher->listen("eloquent.{$event}: {$name}", $callback);
  117. }
  118. }
  119. /**
  120. * Fire the given event for the model.
  121. *
  122. * @param string $event
  123. * @param bool $halt
  124. * @return mixed
  125. */
  126. protected function fireModelEvent($event, $halt = true)
  127. {
  128. if (! isset(static::$dispatcher)) {
  129. return true;
  130. }
  131. // First, we will get the proper method to call on the event dispatcher, and then we
  132. // will attempt to fire a custom, object based event for the given event. If that
  133. // returns a result we can return that result, or we'll call the string events.
  134. $method = $halt ? 'until' : 'fire';
  135. $result = $this->filterModelEventResults(
  136. $this->fireCustomModelEvent($event, $method)
  137. );
  138. if ($result === false) {
  139. return false;
  140. }
  141. return ! empty($result) ? $result : static::$dispatcher->{$method}(
  142. "eloquent.{$event}: ".static::class, $this
  143. );
  144. }
  145. /**
  146. * Fire a custom model event for the given event.
  147. *
  148. * @param string $event
  149. * @param string $method
  150. * @return mixed|null
  151. */
  152. protected function fireCustomModelEvent($event, $method)
  153. {
  154. if (! isset($this->dispatchesEvents[$event])) {
  155. return;
  156. }
  157. $result = static::$dispatcher->$method(new $this->dispatchesEvents[$event]($this));
  158. if (! is_null($result)) {
  159. return $result;
  160. }
  161. }
  162. /**
  163. * Filter the model event results.
  164. *
  165. * @param mixed $result
  166. * @return mixed
  167. */
  168. protected function filterModelEventResults($result)
  169. {
  170. if (is_array($result)) {
  171. $result = array_filter($result, function ($response) {
  172. return ! is_null($response);
  173. });
  174. }
  175. return $result;
  176. }
  177. /**
  178. * Register a retrieved model event with the dispatcher.
  179. *
  180. * @param \Closure|string $callback
  181. * @return void
  182. */
  183. public static function retrieved($callback)
  184. {
  185. static::registerModelEvent('retrieved', $callback);
  186. }
  187. /**
  188. * Register a saving model event with the dispatcher.
  189. *
  190. * @param \Closure|string $callback
  191. * @return void
  192. */
  193. public static function saving($callback)
  194. {
  195. static::registerModelEvent('saving', $callback);
  196. }
  197. /**
  198. * Register a saved model event with the dispatcher.
  199. *
  200. * @param \Closure|string $callback
  201. * @return void
  202. */
  203. public static function saved($callback)
  204. {
  205. static::registerModelEvent('saved', $callback);
  206. }
  207. /**
  208. * Register an updating model event with the dispatcher.
  209. *
  210. * @param \Closure|string $callback
  211. * @return void
  212. */
  213. public static function updating($callback)
  214. {
  215. static::registerModelEvent('updating', $callback);
  216. }
  217. /**
  218. * Register an updated model event with the dispatcher.
  219. *
  220. * @param \Closure|string $callback
  221. * @return void
  222. */
  223. public static function updated($callback)
  224. {
  225. static::registerModelEvent('updated', $callback);
  226. }
  227. /**
  228. * Register a creating model event with the dispatcher.
  229. *
  230. * @param \Closure|string $callback
  231. * @return void
  232. */
  233. public static function creating($callback)
  234. {
  235. static::registerModelEvent('creating', $callback);
  236. }
  237. /**
  238. * Register a created model event with the dispatcher.
  239. *
  240. * @param \Closure|string $callback
  241. * @return void
  242. */
  243. public static function created($callback)
  244. {
  245. static::registerModelEvent('created', $callback);
  246. }
  247. /**
  248. * Register a deleting model event with the dispatcher.
  249. *
  250. * @param \Closure|string $callback
  251. * @return void
  252. */
  253. public static function deleting($callback)
  254. {
  255. static::registerModelEvent('deleting', $callback);
  256. }
  257. /**
  258. * Register a deleted model event with the dispatcher.
  259. *
  260. * @param \Closure|string $callback
  261. * @return void
  262. */
  263. public static function deleted($callback)
  264. {
  265. static::registerModelEvent('deleted', $callback);
  266. }
  267. /**
  268. * Remove all of the event listeners for the model.
  269. *
  270. * @return void
  271. */
  272. public static function flushEventListeners()
  273. {
  274. if (! isset(static::$dispatcher)) {
  275. return;
  276. }
  277. $instance = new static;
  278. foreach ($instance->getObservableEvents() as $event) {
  279. static::$dispatcher->forget("eloquent.{$event}: ".static::class);
  280. }
  281. foreach (array_values($instance->dispatchesEvents) as $event) {
  282. static::$dispatcher->forget($event);
  283. }
  284. }
  285. /**
  286. * Get the event dispatcher instance.
  287. *
  288. * @return \Illuminate\Contracts\Events\Dispatcher
  289. */
  290. public static function getEventDispatcher()
  291. {
  292. return static::$dispatcher;
  293. }
  294. /**
  295. * Set the event dispatcher instance.
  296. *
  297. * @param \Illuminate\Contracts\Events\Dispatcher $dispatcher
  298. * @return void
  299. */
  300. public static function setEventDispatcher(Dispatcher $dispatcher)
  301. {
  302. static::$dispatcher = $dispatcher;
  303. }
  304. /**
  305. * Unset the event dispatcher for models.
  306. *
  307. * @return void
  308. */
  309. public static function unsetEventDispatcher()
  310. {
  311. static::$dispatcher = null;
  312. }
  313. }