[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   * Interface for event dispatchers.
  13   *
  14   * @since  1.0
  15   */
  16  interface DispatcherInterface
  17  {
  18      /**
  19       * Dispatches an event to all registered listeners.
  20       *
  21       * @param   string          $name   The name of the event to dispatch.
  22       * @param   EventInterface  $event  The event to pass to the event handlers/listeners.
  23       *                                  If not supplied, an empty EventInterface instance is created.
  24       *                                  Note, not passing an event is deprecated and will be required as of 3.0.
  25       *
  26       * @return  EventInterface
  27       *
  28       * @since   2.0.0
  29       */
  30  	public function dispatch(string $name, ?EventInterface $event = null): EventInterface;
  31  
  32      /**
  33       * Attaches a listener to an event
  34       *
  35       * @param   string    $eventName  The event to listen to.
  36       * @param   callable  $callback   A callable function.
  37       * @param   integer   $priority   The priority at which the $callback executed.
  38       *
  39       * @return  boolean
  40       *
  41       * @since   2.0.0
  42       */
  43  	public function addListener(string $eventName, callable $callback, int $priority = 0): bool;
  44  
  45      /**
  46       * Clear the listeners in this dispatcher.
  47       *
  48       * If an event is specified, the listeners will be cleared only for that event.
  49       *
  50       * @param   string  $event  The event name.
  51       *
  52       * @return  $this
  53       *
  54       * @since   2.0.0
  55       */
  56  	public function clearListeners($event = null);
  57  
  58      /**
  59       * Count the number of registered listeners for the given event.
  60       *
  61       * @param   string  $event  The event name.
  62       *
  63       * @return  integer
  64       *
  65       * @since   2.0.0
  66       */
  67  	public function countListeners($event);
  68  
  69      /**
  70       * Get the listeners registered to the given event.
  71       *
  72       * @param   string|null  $event  The event to fetch listeners for or null to fetch all listeners
  73       *
  74       * @return  callable[]  An array of registered listeners sorted according to their priorities.
  75       *
  76       * @since   2.0.0
  77       */
  78  	public function getListeners(?string $event = null);
  79  
  80      /**
  81       * Tell if the given listener has been added.
  82       *
  83       * If an event is specified, it will tell if the listener is registered for that event.
  84       *
  85       * @param   callable     $callback   The callable to check is listening to the event.
  86       * @param   string|null  $eventName  An optional event name to check a listener is subscribed to.
  87       *
  88       * @return  boolean  True if the listener is registered, false otherwise.
  89       *
  90       * @since   2.0.0
  91       */
  92  	public function hasListener(callable $callback, ?string $eventName = null);
  93  
  94      /**
  95       * Removes an event listener from the specified event.
  96       *
  97       * @param   string    $eventName  The event to remove a listener from.
  98       * @param   callable  $listener   The listener to remove.
  99       *
 100       * @return  void
 101       *
 102       * @since   2.0.0
 103       */
 104  	public function removeListener(string $eventName, callable $listener): void;
 105  
 106      /**
 107       * Adds an event subscriber.
 108       *
 109       * @param   SubscriberInterface  $subscriber  The subscriber.
 110       *
 111       * @return  void
 112       *
 113       * @since   2.0.0
 114       */
 115  	public function addSubscriber(SubscriberInterface $subscriber): void;
 116  
 117      /**
 118       * Removes an event subscriber.
 119       *
 120       * @param   SubscriberInterface  $subscriber  The subscriber.
 121       *
 122       * @return  void
 123       *
 124       * @since   2.0.0
 125       */
 126  	public function removeSubscriber(SubscriberInterface $subscriber): void;
 127  }