1<?php
2/**
3 * Zend Framework (http://framework.zend.com/)
4 *
5 * @link      http://github.com/zendframework/zf2 for the canonical source repository
6 * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
7 * @license   http://framework.zend.com/license/new-bsd New BSD License
8 */
9
10namespace Zend\EventManager;
11
12use Traversable;
13use Zend\Stdlib\CallbackHandler;
14
15/**
16 * Interface for messengers
17 */
18interface EventManagerInterface extends SharedEventManagerAwareInterface
19{
20    /**
21     * Trigger an event
22     *
23     * Should allow handling the following scenarios:
24     * - Passing Event object only
25     * - Passing event name and Event object only
26     * - Passing event name, target, and Event object
27     * - Passing event name, target, and array|ArrayAccess of arguments
28     * - Passing event name, target, array|ArrayAccess of arguments, and callback
29     *
30     * @param  string|EventInterface $event
31     * @param  object|string $target
32     * @param  array|object $argv
33     * @param  null|callable $callback
34     * @return ResponseCollection
35     */
36    public function trigger($event, $target = null, $argv = array(), $callback = null);
37
38    /**
39     * Trigger an event until the given callback returns a boolean true
40     *
41     * Should allow handling the following scenarios:
42     * - Passing Event object and callback only
43     * - Passing event name, Event object, and callback only
44     * - Passing event name, target, Event object, and callback
45     * - Passing event name, target, array|ArrayAccess of arguments, and callback
46     *
47     * @param  string|EventInterface $event
48     * @param  object|string $target
49     * @param  array|object $argv
50     * @param  callable $callback
51     * @return ResponseCollection
52     * @deprecated Please use trigger()
53     */
54    public function triggerUntil($event, $target, $argv = null, $callback = null);
55
56    /**
57     * Attach a listener to an event
58     *
59     * @param  string $event
60     * @param  callable $callback
61     * @param  int $priority Priority at which to register listener
62     * @return CallbackHandler
63     */
64    public function attach($event, $callback = null, $priority = 1);
65
66    /**
67     * Detach an event listener
68     *
69     * @param  CallbackHandler|ListenerAggregateInterface $listener
70     * @return bool
71     */
72    public function detach($listener);
73
74    /**
75     * Get a list of events for which this collection has listeners
76     *
77     * @return array
78     */
79    public function getEvents();
80
81    /**
82     * Retrieve a list of listeners registered to a given event
83     *
84     * @param  string $event
85     * @return array|object
86     */
87    public function getListeners($event);
88
89    /**
90     * Clear all listeners for a given event
91     *
92     * @param  string $event
93     * @return void
94     */
95    public function clearListeners($event);
96
97    /**
98     * Set the event class to utilize
99     *
100     * @param  string $class
101     * @return EventManagerInterface
102     */
103    public function setEventClass($class);
104
105    /**
106     * Get the identifier(s) for this EventManager
107     *
108     * @return array
109     */
110    public function getIdentifiers();
111
112    /**
113     * Set the identifiers (overrides any currently set identifiers)
114     *
115     * @param string|int|array|Traversable $identifiers
116     * @return EventManagerInterface
117     */
118    public function setIdentifiers($identifiers);
119
120    /**
121     * Add some identifier(s) (appends to any currently set identifiers)
122     *
123     * @param string|int|array|Traversable $identifiers
124     * @return EventManagerInterface
125     */
126    public function addIdentifiers($identifiers);
127
128    /**
129     * Attach a listener aggregate
130     *
131     * @param  ListenerAggregateInterface $aggregate
132     * @param  int $priority If provided, a suggested priority for the aggregate to use
133     * @return mixed return value of {@link ListenerAggregateInterface::attach()}
134     */
135    public function attachAggregate(ListenerAggregateInterface $aggregate, $priority = 1);
136
137    /**
138     * Detach a listener aggregate
139     *
140     * @param  ListenerAggregateInterface $aggregate
141     * @return mixed return value of {@link ListenerAggregateInterface::detach()}
142     */
143    public function detachAggregate(ListenerAggregateInterface $aggregate);
144}
145