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:      * Adds a new listener to an event.
 23:      *
 24:      * A variadic interface to add listeners that emulates jQuery.on().
 25:      *
 26:      * Binding an EventListenerInterface:
 27:      *
 28:      * ```
 29:      * $eventManager->on($listener);
 30:      * ```
 31:      *
 32:      * Binding with no options:
 33:      *
 34:      * ```
 35:      * $eventManager->on('Model.beforeSave', $callable);
 36:      * ```
 37:      *
 38:      * Binding with options:
 39:      *
 40:      * ```
 41:      * $eventManager->on('Model.beforeSave', ['priority' => 90], $callable);
 42:      * ```
 43:      *
 44:      * @param string|\Cake\Event\EventListenerInterface|null $eventKey The event unique identifier name
 45:      * with which the callback will be associated. If $eventKey is an instance of
 46:      * Cake\Event\EventListenerInterface its events will be bound using the `implementedEvents` methods.
 47:      *
 48:      * @param array|callable $options Either an array of options or the callable you wish to
 49:      * bind to $eventKey. If an array of options, the `priority` key can be used to define the order.
 50:      * Priorities are treated as queues. Lower values are called before higher ones, and multiple attachments
 51:      * added to the same priority queue will be treated in the order of insertion.
 52:      *
 53:      * @param callable|null $callable The callable function you want invoked.
 54:      *
 55:      * @return $this
 56:      * @throws \InvalidArgumentException When event key is missing or callable is not an
 57:      *   instance of Cake\Event\EventListenerInterface.
 58:      */
 59:     public function on($eventKey = null, $options = [], $callable = null);
 60: 
 61:     /**
 62:      * Remove a listener from the active listeners.
 63:      *
 64:      * Remove a EventListenerInterface entirely:
 65:      *
 66:      * ```
 67:      * $manager->off($listener);
 68:      * ```
 69:      *
 70:      * Remove all listeners for a given event:
 71:      *
 72:      * ```
 73:      * $manager->off('My.event');
 74:      * ```
 75:      *
 76:      * Remove a specific listener:
 77:      *
 78:      * ```
 79:      * $manager->off('My.event', $callback);
 80:      * ```
 81:      *
 82:      * Remove a callback from all events:
 83:      *
 84:      * ```
 85:      * $manager->off($callback);
 86:      * ```
 87:      *
 88:      * @param string|\Cake\Event\EventListenerInterface $eventKey The event unique identifier name
 89:      *   with which the callback has been associated, or the $listener you want to remove.
 90:      * @param callable|null $callable The callback you want to detach.
 91:      * @return $this
 92:      */
 93:     public function off($eventKey, $callable = null);
 94: 
 95:     /**
 96:      * Dispatches a new event to all configured listeners
 97:      *
 98:      * @param string|\Cake\Event\EventInterface $event The event key name or instance of EventInterface.
 99:      * @return \Cake\Event\EventInterface
100:      * @triggers $event
101:      */
102:     public function dispatch($event);
103: 
104:     /**
105:      * Returns a list of all listeners for an eventKey in the order they should be called
106:      *
107:      * @param string $eventKey Event key.
108:      * @return array
109:      */
110:     public function listeners($eventKey);
111: }
112: