[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Part of the Joomla Framework Event Package
   4   *
   5   * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
   6   * @license    GNU General Public License version 2 or later; see LICENSE
   7   */
   8  
   9  namespace Joomla\Event;
  10  
  11  /**
  12   * Implementation of a DispatcherInterface supporting prioritized listeners.
  13   *
  14   * @since  1.0
  15   */
  16  class Dispatcher implements DispatcherInterface
  17  {
  18      /**
  19       * An array of registered events indexed by the event names.
  20       *
  21       * @var    EventInterface[]
  22       * @since  1.0
  23       * @deprecated  3.0  Default event objects will no longer be supported
  24       */
  25      protected $events = [];
  26  
  27      /**
  28       * An array of ListenersPriorityQueue indexed by the event names.
  29       *
  30       * @var    ListenersPriorityQueue[]
  31       * @since  1.0
  32       */
  33      protected $listeners = [];
  34  
  35      /**
  36       * Set an event to the dispatcher. It will replace any event with the same name.
  37       *
  38       * @param   EventInterface  $event  The event.
  39       *
  40       * @return  $this
  41       *
  42       * @since   1.0
  43       * @deprecated  3.0  Default event objects will no longer be supported
  44       */
  45  	public function setEvent(EventInterface $event)
  46      {
  47          trigger_deprecation(
  48              'joomla/event',
  49              '2.0.0',
  50              '%s() is deprecated and will be removed in 3.0.',
  51              __METHOD__
  52          );
  53  
  54          $this->events[$event->getName()] = $event;
  55  
  56          return $this;
  57      }
  58  
  59      /**
  60       * Add an event to this dispatcher, only if it is not existing.
  61       *
  62       * @param   EventInterface  $event  The event.
  63       *
  64       * @return  $this
  65       *
  66       * @since   1.0
  67       * @deprecated  3.0  Default event objects will no longer be supported
  68       */
  69  	public function addEvent(EventInterface $event)
  70      {
  71          trigger_deprecation(
  72              'joomla/event',
  73              '2.0.0',
  74              '%s() is deprecated and will be removed in 3.0.',
  75              __METHOD__
  76          );
  77  
  78          if (!isset($this->events[$event->getName()]))
  79          {
  80              $this->events[$event->getName()] = $event;
  81          }
  82  
  83          return $this;
  84      }
  85  
  86      /**
  87       * Tell if the given event has been added to this dispatcher.
  88       *
  89       * @param   EventInterface|string  $event  The event object or name.
  90       *
  91       * @return  boolean  True if the listener has the given event, false otherwise.
  92       *
  93       * @since   1.0
  94       * @deprecated  3.0  Default event objects will no longer be supported
  95       */
  96  	public function hasEvent($event)
  97      {
  98          trigger_deprecation(
  99              'joomla/event',
 100              '2.0.0',
 101              '%s() is deprecated and will be removed in 3.0.',
 102              __METHOD__
 103          );
 104  
 105          if ($event instanceof EventInterface)
 106          {
 107              $event = $event->getName();
 108          }
 109  
 110          return isset($this->events[$event]);
 111      }
 112  
 113      /**
 114       * Get the event object identified by the given name.
 115       *
 116       * @param   string  $name     The event name.
 117       * @param   mixed   $default  The default value if the event was not registered.
 118       *
 119       * @return  EventInterface|mixed  The event of the default value.
 120       *
 121       * @since   1.0
 122       * @deprecated  3.0  Default event objects will no longer be supported
 123       */
 124  	public function getEvent($name, $default = null)
 125      {
 126          trigger_deprecation(
 127              'joomla/event',
 128              '2.0.0',
 129              '%s() is deprecated and will be removed in 3.0.',
 130              __METHOD__
 131          );
 132  
 133          if (isset($this->events[$name]))
 134          {
 135              return $this->events[$name];
 136          }
 137  
 138          return $default;
 139      }
 140  
 141      /**
 142       * Remove an event from this dispatcher. The registered listeners will remain.
 143       *
 144       * @param   EventInterface|string  $event  The event object or name.
 145       *
 146       * @return  $this
 147       *
 148       * @since   1.0
 149       * @deprecated  3.0  Default event objects will no longer be supported
 150       */
 151  	public function removeEvent($event)
 152      {
 153          trigger_deprecation(
 154              'joomla/event',
 155              '2.0.0',
 156              '%s() is deprecated and will be removed in 3.0.',
 157              __METHOD__
 158          );
 159  
 160          if ($event instanceof EventInterface)
 161          {
 162              $event = $event->getName();
 163          }
 164  
 165          if (isset($this->events[$event]))
 166          {
 167              unset($this->events[$event]);
 168          }
 169  
 170          return $this;
 171      }
 172  
 173      /**
 174       * Get the registered events.
 175       *
 176       * @return  EventInterface[]  The registered event.
 177       *
 178       * @since   1.0
 179       * @deprecated  3.0  Default event objects will no longer be supported
 180       */
 181  	public function getEvents()
 182      {
 183          trigger_deprecation(
 184              'joomla/event',
 185              '2.0.0',
 186              '%s() is deprecated and will be removed in 3.0.',
 187              __METHOD__
 188          );
 189  
 190          return $this->events;
 191      }
 192  
 193      /**
 194       * Clear all events.
 195       *
 196       * @return  EventInterface[]  The old events.
 197       *
 198       * @since   1.0
 199       * @deprecated  3.0  Default event objects will no longer be supported
 200       */
 201  	public function clearEvents()
 202      {
 203          trigger_deprecation(
 204              'joomla/event',
 205              '2.0.0',
 206              '%s() is deprecated and will be removed in 3.0.',
 207              __METHOD__
 208          );
 209  
 210          $events       = $this->events;
 211          $this->events = [];
 212  
 213          return $events;
 214      }
 215  
 216      /**
 217       * Count the number of registered event.
 218       *
 219       * @return  integer  The numer of registered events.
 220       *
 221       * @since   1.0
 222       * @deprecated  3.0  Default event objects will no longer be supported
 223       */
 224  	public function countEvents()
 225      {
 226          trigger_deprecation(
 227              'joomla/event',
 228              '2.0.0',
 229              '%s() is deprecated and will be removed in 3.0.',
 230              __METHOD__
 231          );
 232  
 233          return \count($this->events);
 234      }
 235  
 236      /**
 237       * Attaches a listener to an event
 238       *
 239       * @param   string    $eventName  The event to listen to.
 240       * @param   callable  $callback   A callable function
 241       * @param   integer   $priority   The priority at which the $callback executed
 242       *
 243       * @return  boolean
 244       *
 245       * @since   1.0
 246       */
 247  	public function addListener(string $eventName, callable $callback, int $priority = 0): bool
 248      {
 249          if (!isset($this->listeners[$eventName]))
 250          {
 251              $this->listeners[$eventName] = new ListenersPriorityQueue;
 252          }
 253  
 254          $this->listeners[$eventName]->add($callback, $priority);
 255  
 256          return true;
 257      }
 258  
 259      /**
 260       * Get the priority of the given listener for the given event.
 261       *
 262       * @param   string    $eventName  The event to listen to.
 263       * @param   callable  $callback   A callable function
 264       *
 265       * @return  mixed  The listener priority or null if the listener doesn't exist.
 266       *
 267       * @since   1.0
 268       */
 269  	public function getListenerPriority($eventName, callable $callback)
 270      {
 271          if (isset($this->listeners[$eventName]))
 272          {
 273              return $this->listeners[$eventName]->getPriority($callback);
 274          }
 275      }
 276  
 277      /**
 278       * Get the listeners registered to the given event.
 279       *
 280       * @param   string|null  $event  The event to fetch listeners for or null to fetch all listeners
 281       *
 282       * @return  callable[]  An array of registered listeners sorted according to their priorities.
 283       *
 284       * @since   1.0
 285       */
 286  	public function getListeners(?string $event = null)
 287      {
 288          if ($event !== null)
 289          {
 290              if (isset($this->listeners[$event]))
 291              {
 292                  return $this->listeners[$event]->getAll();
 293              }
 294  
 295              return [];
 296          }
 297  
 298          $dispatcherListeners = [];
 299  
 300          foreach ($this->listeners as $registeredEvent => $listeners)
 301          {
 302              $dispatcherListeners[$registeredEvent] = $listeners->getAll();
 303          }
 304  
 305          return $dispatcherListeners;
 306      }
 307  
 308      /**
 309       * Tell if the given listener has been added.
 310       *
 311       * If an event is specified, it will tell if the listener is registered for that event.
 312       *
 313       * @param   callable  $callback   The callable to check is listening to the event.
 314       * @param   string    $eventName  An optional event name to check a listener is subscribed to.
 315       *
 316       * @return  boolean  True if the listener is registered, false otherwise.
 317       *
 318       * @since   1.0
 319       */
 320  	public function hasListener(callable $callback, ?string $eventName = null)
 321      {
 322          if ($eventName)
 323          {
 324              if (isset($this->listeners[$eventName]))
 325              {
 326                  return $this->listeners[$eventName]->has($callback);
 327              }
 328          }
 329          else
 330          {
 331              foreach ($this->listeners as $queue)
 332              {
 333                  if ($queue->has($callback))
 334                  {
 335                      return true;
 336                  }
 337              }
 338          }
 339  
 340          return false;
 341      }
 342  
 343      /**
 344       * Removes an event listener from the specified event.
 345       *
 346       * @param   string    $eventName  The event to remove a listener from.
 347       * @param   callable  $listener   The listener to remove.
 348       *
 349       * @return  void
 350       *
 351       * @since   2.0.0
 352       */
 353  	public function removeListener(string $eventName, callable $listener): void
 354      {
 355          if (isset($this->listeners[$eventName]))
 356          {
 357              $this->listeners[$eventName]->remove($listener);
 358          }
 359      }
 360  
 361      /**
 362       * Clear the listeners in this dispatcher.
 363       *
 364       * If an event is specified, the listeners will be cleared only for that event.
 365       *
 366       * @param   string  $event  The event name.
 367       *
 368       * @return  $this
 369       *
 370       * @since   1.0
 371       */
 372  	public function clearListeners($event = null)
 373      {
 374          if ($event)
 375          {
 376              if (isset($this->listeners[$event]))
 377              {
 378                  unset($this->listeners[$event]);
 379              }
 380          }
 381          else
 382          {
 383              $this->listeners = [];
 384          }
 385  
 386          return $this;
 387      }
 388  
 389      /**
 390       * Count the number of registered listeners for the given event.
 391       *
 392       * @param   string  $event  The event name.
 393       *
 394       * @return  integer
 395       *
 396       * @since   1.0
 397       */
 398  	public function countListeners($event)
 399      {
 400          return isset($this->listeners[$event]) ? \count($this->listeners[$event]) : 0;
 401      }
 402  
 403      /**
 404       * Adds an event subscriber.
 405       *
 406       * @param   SubscriberInterface  $subscriber  The subscriber.
 407       *
 408       * @return  void
 409       *
 410       * @since   2.0.0
 411       */
 412  	public function addSubscriber(SubscriberInterface $subscriber): void
 413      {
 414          foreach ($subscriber->getSubscribedEvents() as $eventName => $params)
 415          {
 416              if (\is_array($params))
 417              {
 418                  $this->addListener($eventName, [$subscriber, $params[0]], $params[1] ?? Priority::NORMAL);
 419              }
 420              else
 421              {
 422                  $this->addListener($eventName, [$subscriber, $params]);
 423              }
 424          }
 425      }
 426  
 427      /**
 428       * Removes an event subscriber.
 429       *
 430       * @param   SubscriberInterface  $subscriber  The subscriber.
 431       *
 432       * @return  void
 433       *
 434       * @since   2.0.0
 435       */
 436  	public function removeSubscriber(SubscriberInterface $subscriber): void
 437      {
 438          foreach ($subscriber->getSubscribedEvents() as $eventName => $params)
 439          {
 440              if (\is_array($params))
 441              {
 442                  $this->removeListener($eventName, [$subscriber, $params[0]]);
 443              }
 444              else
 445              {
 446                  $this->removeListener($eventName, [$subscriber, $params]);
 447              }
 448          }
 449      }
 450  
 451      /**
 452       * Dispatches an event to all registered listeners.
 453       *
 454       * @param   string          $name   The name of the event to dispatch.
 455       * @param   EventInterface  $event  The event to pass to the event handlers/listeners.
 456       *                                  If not supplied, an empty EventInterface instance is created.
 457       *                                  Note, not passing an event is deprecated and will be required as of 3.0.
 458       *
 459       * @return  EventInterface
 460       *
 461       * @since   2.0.0
 462       */
 463  	public function dispatch(string $name, ?EventInterface $event = null): EventInterface
 464      {
 465          if (!($event instanceof EventInterface))
 466          {
 467              trigger_deprecation(
 468                  'joomla/event',
 469                  '2.0.0',
 470                  'Not passing an event object to %s() is deprecated, as of 3.0 the $event argument will be required.',
 471                  __METHOD__
 472              );
 473  
 474              $event = $this->getDefaultEvent($name);
 475          }
 476  
 477          if (isset($this->listeners[$event->getName()]))
 478          {
 479              foreach ($this->listeners[$event->getName()] as $listener)
 480              {
 481                  if ($event->isStopped())
 482                  {
 483                      return $event;
 484                  }
 485  
 486                  $listener($event);
 487              }
 488          }
 489  
 490          return $event;
 491      }
 492  
 493      /**
 494       * Trigger an event.
 495       *
 496       * @param   EventInterface|string  $event  The event object or name.
 497       *
 498       * @return  EventInterface  The event after being passed through all listeners.
 499       *
 500       * @since   1.0
 501       * @deprecated  3.0  Use dispatch() instead.
 502       */
 503  	public function triggerEvent($event)
 504      {
 505          trigger_deprecation(
 506              'joomla/event',
 507              '2.0.0',
 508              '%s() is deprecated and will be removed in 3.0, use %s::dispatch() instead.',
 509              __METHOD__,
 510              DispatcherInterface::class
 511          );
 512  
 513          if (!($event instanceof EventInterface))
 514          {
 515              $event = $this->getDefaultEvent($event);
 516          }
 517  
 518          return $this->dispatch($event->getName(), $event);
 519      }
 520  
 521      /**
 522       * Get an event object for the specified event name
 523       *
 524       * @param   string  $name  The event name to get an EventInterface object for
 525       *
 526       * @return  EventInterface
 527       *
 528       * @since   2.0.0
 529       * @deprecated  3.0  Default event objects will no longer be supported
 530       */
 531  	private function getDefaultEvent(string $name): EventInterface
 532      {
 533          if (isset($this->events[$name]))
 534          {
 535              return $this->events[$name];
 536          }
 537  
 538          return new Event($name);
 539      }
 540  }