[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Zend Framework (http://framework.zend.com/)
   4   *
   5   * @link      http://github.com/zendframework/zend-eventmanager for the canonical source repository
   6   * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
   7   * @license   https://github.com/zendframework/zend-eventmanager/blob/master/LICENSE.md
   8   */
   9  
  10  namespace Zend\EventManager;
  11  
  12  /**
  13   * Interface for messengers
  14   */
  15  interface EventManagerInterface extends SharedEventsCapableInterface
  16  {
  17      /**
  18       * Create and trigger an event.
  19       *
  20       * Use this method when you do not want to create an EventInterface
  21       * instance prior to triggering. You will be required to pass:
  22       *
  23       * - the event name
  24       * - the event target (can be null)
  25       * - any event parameters you want to provide (empty array by default)
  26       *
  27       * It will create the Event instance for you and then trigger all listeners
  28       * related to the event.
  29       *
  30       * @param  string $eventName
  31       * @param  null|object|string $target
  32       * @param  array|object $argv
  33       * @return ResponseCollection
  34       */
  35      public function trigger($eventName, $target = null, $argv = []);
  36  
  37      /**
  38       * Create and trigger an event, applying a callback to each listener result.
  39       *
  40       * Use this method when you do not want to create an EventInterface
  41       * instance prior to triggering. You will be required to pass:
  42       *
  43       * - the event name
  44       * - the event target (can be null)
  45       * - any event parameters you want to provide (empty array by default)
  46       *
  47       * It will create the Event instance for you, and trigger all listeners
  48       * related to the event.
  49       *
  50       * The result of each listener is passed to $callback; if $callback returns
  51       * a boolean true value, the manager must short-circuit listener execution.
  52       *
  53       * @param  callable $callback
  54       * @param  string $eventName
  55       * @param  null|object|string $target
  56       * @param  array|object $argv
  57       * @return ResponseCollection
  58       */
  59      public function triggerUntil(callable $callback, $eventName, $target = null, $argv = []);
  60  
  61      /**
  62       * Trigger an event
  63       *
  64       * Provided an EventInterface instance, this method will trigger listeners
  65       * based on the event name, raising an exception if the event name is missing.
  66       *
  67       * @param  EventInterface $event
  68       * @return ResponseCollection
  69       */
  70      public function triggerEvent(EventInterface $event);
  71  
  72      /**
  73       * Trigger an event, applying a callback to each listener result.
  74       *
  75       * Provided an EventInterface instance, this method will trigger listeners
  76       * based on the event name, raising an exception if the event name is missing.
  77       *
  78       * The result of each listener is passed to $callback; if $callback returns
  79       * a boolean true value, the manager must short-circuit listener execution.
  80       *
  81       * @param  callable $callback
  82       * @param  EventInterface $event
  83       * @return ResponseCollection
  84       */
  85      public function triggerEventUntil(callable $callback, EventInterface $event);
  86  
  87      /**
  88       * Attach a listener to an event
  89       *
  90       * The first argument is the event, and the next argument is a
  91       * callable that will respond to that event.
  92       *
  93       * The last argument indicates a priority at which the event should be
  94       * executed; by default, this value is 1; however, you may set it for any
  95       * integer value. Higher values have higher priority (i.e., execute first).
  96       *
  97       * You can specify "*" for the event name. In such cases, the listener will
  98       * be triggered for every event *that has registered listeners at the time
  99       * it is attached*. As such, register wildcard events last whenever possible!
 100       *
 101       * @param  string $eventName Event to which to listen.
 102       * @param  callable $listener
 103       * @param  int $priority Priority at which to register listener.
 104       * @return callable
 105       */
 106      public function attach($eventName, callable $listener, $priority = 1);
 107  
 108      /**
 109       * Detach a listener.
 110       *
 111       * If no $event or '*' is provided, detaches listener from all events;
 112       * otherwise, detaches only from the named event.
 113       *
 114       * @param callable $listener
 115       * @param null|string $eventName Event from which to detach; null and '*'
 116       *     indicate all events.
 117       * @return void
 118       */
 119      public function detach(callable $listener, $eventName = null);
 120  
 121      /**
 122       * Clear all listeners for a given event
 123       *
 124       * @param  string $eventName
 125       * @return void
 126       */
 127      public function clearListeners($eventName);
 128  
 129      /**
 130       * Provide an event prototype to use with trigger().
 131       *
 132       * When `trigger()` needs to create an event instance, it should clone the
 133       * prototype provided to this method.
 134       *
 135       * @param  EventInterface $prototype
 136       * @return void
 137       */
 138      public function setEventPrototype(EventInterface $prototype);
 139  
 140      /**
 141       * Get the identifier(s) for this EventManager
 142       *
 143       * @return array
 144       */
 145      public function getIdentifiers();
 146  
 147      /**
 148       * Set the identifiers (overrides any currently set identifiers)
 149       *
 150       * @param  string[] $identifiers
 151       * @return void
 152       */
 153      public function setIdentifiers(array $identifiers);
 154  
 155      /**
 156       * Add identifier(s) (appends to any currently set identifiers)
 157       *
 158       * @param  string[] $identifiers
 159       * @return void
 160       */
 161      public function addIdentifiers(array $identifiers);
 162  }