1: <?php
  2: /**
  3:  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
  4:  * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
  5:  * Licensed under The MIT License
  6:  * For full copyright and license information, please see the LICENSE.txt
  7:  * Redistributions of files must retain the above copyright notice.
  8:  *
  9:  * @copyright     Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
 10:  * @link          http://cakephp.org CakePHP(tm) Project
 11:  * @since         3.6.0
 12:  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
 13:  */
 14: namespace Cake\Event;
 15: 
 16: /**
 17:  * Interface EventManagerInterface
 18:  */
 19: interface EventManagerInterface
 20: {
 21: 
 22:     /**
 23:      * Adds a new listener to an event.
 24:      *
 25:      * A variadic interface to add listeners that emulates jQuery.on().
 26:      *
 27:      * Binding an EventListenerInterface:
 28:      *
 29:      * ```
 30:      * $eventManager->on($listener);
 31:      * ```
 32:      *
 33:      * Binding with no options:
 34:      *
 35:      * ```
 36:      * $eventManager->on('Model.beforeSave', $callable);
 37:      * ```
 38:      *
 39:      * Binding with options:
 40:      *
 41:      * ```
 42:      * $eventManager->on('Model.beforeSave', ['priority' => 90], $callable);
 43:      * ```
 44:      *
 45:      * @param string|\Cake\Event\EventListenerInterface|null $eventKey The event unique identifier name
 46:      * with which the callback will be associated. If $eventKey is an instance of
 47:      * Cake\Event\EventListenerInterface its events will be bound using the `implementedEvents` methods.
 48:      *
 49:      * @param array|callable $options Either an array of options or the callable you wish to
 50:      * bind to $eventKey. If an array of options, the `priority` key can be used to define the order.
 51:      * Priorities are treated as queues. Lower values are called before higher ones, and multiple attachments
 52:      * added to the same priority queue will be treated in the order of insertion.
 53:      *
 54:      * @param callable|null $callable The callable function you want invoked.
 55:      *
 56:      * @return $this
 57:      * @throws \InvalidArgumentException When event key is missing or callable is not an
 58:      *   instance of Cake\Event\EventListenerInterface.
 59:      */
 60:     public function on($eventKey = null, $options = [], $callable = null);
 61: 
 62:     /**
 63:      * Remove a listener from the active listeners.
 64:      *
 65:      * Remove a EventListenerInterface entirely:
 66:      *
 67:      * ```
 68:      * $manager->off($listener);
 69:      * ```
 70:      *
 71:      * Remove all listeners for a given event:
 72:      *
 73:      * ```
 74:      * $manager->off('My.event');
 75:      * ```
 76:      *
 77:      * Remove a specific listener:
 78:      *
 79:      * ```
 80:      * $manager->off('My.event', $callback);
 81:      * ```
 82:      *
 83:      * Remove a callback from all events:
 84:      *
 85:      * ```
 86:      * $manager->off($callback);
 87:      * ```
 88:      *
 89:      * @param string|\Cake\Event\EventListenerInterface $eventKey The event unique identifier name
 90:      *   with which the callback has been associated, or the $listener you want to remove.
 91:      * @param callable|null $callable The callback you want to detach.
 92:      * @return $this
 93:      */
 94:     public function off($eventKey, $callable = null);
 95: 
 96:     /**
 97:      * Dispatches a new event to all configured listeners
 98:      *
 99:      * @param string|\Cake\Event\EventInterface $event The event key name or instance of EventInterface.
100:      * @return \Cake\Event\EventInterface
101:      * @triggers $event
102:      */
103:     public function dispatch($event);
104: 
105:     /**
106:      * Returns a list of all listeners for an eventKey in the order they should be called
107:      *
108:      * @param string $eventKey Event key.
109:      * @return array
110:      */
111:     public function listeners($eventKey);
112: }
113: