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
10namespace Zend\EventManager;
11
12/**
13 * Interface for messengers
14 */
15interface 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}
163