1<?php
2namespace GuzzleHttp\Event;
3
4/**
5 * Guzzle event emitter.
6 */
7interface EmitterInterface
8{
9    /**
10     * Binds a listener to a specific event.
11     *
12     * @param string     $eventName Name of the event to bind to.
13     * @param callable   $listener  Listener to invoke when triggered.
14     * @param int|string $priority  The higher this value, the earlier an event
15     *     listener will be triggered in the chain (defaults to 0). You can
16     *     pass "first" or "last" to dynamically specify the event priority
17     *     based on the current event priorities associated with the given
18     *     event name in the emitter. Use "first" to set the priority to the
19     *     current highest priority plus one. Use "last" to set the priority to
20     *     the current lowest event priority minus one.
21     */
22    public function on($eventName, callable $listener, $priority = 0);
23
24    /**
25     * Binds a listener to a specific event. After the listener is triggered
26     * once, it is removed as a listener.
27     *
28     * @param string   $eventName Name of the event to bind to.
29     * @param callable $listener  Listener to invoke when triggered.
30     * @param int      $priority  The higher this value, the earlier an event
31     *     listener will be triggered in the chain (defaults to 0)
32     */
33    public function once($eventName, callable $listener, $priority = 0);
34
35    /**
36     * Removes an event listener from the specified event.
37     *
38     * @param string   $eventName The event to remove a listener from
39     * @param callable $listener  The listener to remove
40     */
41    public function removeListener($eventName, callable $listener);
42
43    /**
44     * Gets the listeners of a specific event or all listeners if no event is
45     * specified.
46     *
47     * @param string $eventName The name of the event. Pass null (the default)
48     *     to retrieve all listeners.
49     *
50     * @return array The event listeners for the specified event, or all event
51     *   listeners by event name. The format of the array when retrieving a
52     *   specific event list is an array of callables. The format of the array
53     *   when retrieving all listeners is an associative array of arrays of
54     *   callables.
55     */
56    public function listeners($eventName = null);
57
58    /**
59     * Checks if the emitter has listeners by the given name.
60     *
61     * @param string $eventName The name of the event to check.
62     *
63     * @return bool
64     */
65    public function hasListeners($eventName);
66
67    /**
68     * Emits an event to all registered listeners.
69     *
70     * Each event that is bound to the emitted eventName receives a
71     * EventInterface, the name of the event, and the event emitter.
72     *
73     * @param string         $eventName The name of the event to dispatch.
74     * @param EventInterface $event     The event to pass to the event handlers/listeners.
75     *
76     * @return EventInterface Returns the provided event object
77     */
78    public function emit($eventName, EventInterface $event);
79
80    /**
81     * Attaches an event subscriber.
82     *
83     * The subscriber is asked for all the events it is interested in and added
84     * as an event listener for each event.
85     *
86     * @param SubscriberInterface $subscriber Subscriber to attach.
87     */
88    public function attach(SubscriberInterface $subscriber);
89
90    /**
91     * Detaches an event subscriber.
92     *
93     * @param SubscriberInterface $subscriber Subscriber to detach.
94     */
95    public function detach(SubscriberInterface $subscriber);
96}
97