1: <?php
  2: /**
  3:  * This file contains the declaration of the interface IEventManager for event management.
  4:  *
  5:  * @package System
  6:  *
  7:  * @author Oleg Schildt
  8:  */
  9: 
 10: namespace SmartFactory\Interfaces;
 11: 
 12: /**
 13:  * Interface for event management.
 14:  *
 15:  * @author Oleg Schildt
 16:  */
 17: interface IEventManager
 18: {
 19:     /**
 20:      * Adds the handler of an event.
 21:      *
 22:      * @param string $event
 23:      * Event code.
 24:      *
 25:      * @param callable $handler
 26:      * The name or definition of the handler function. The signature of
 27:      * this function is:
 28:      *
 29:      * ```php
 30:      * function (string $event, array $parameters) : void;
 31:      * ```
 32:      *
 33:      * - $event - the event code.
 34:      * - $parameters - parameters passed by the firing of the event.
 35:      *
 36:      * @return void
 37:      *
 38:      * @throws \Exception
 39:      * It might throw an exception in the case of any errors.
 40:      *
 41:      * @see IEventManager::deleteHandler()
 42:      * @see IEventManager::deleteHandlers()
 43:      * @see IEventManager::deleteAllHandlers()
 44:      *
 45:      * @author Oleg Schildt
 46:      */
 47:     public function addHandler(string $event, callable $handler): void;
 48: 
 49:     /**
 50:      * Deletes the handler of an event.
 51:      *
 52:      * @param string $event
 53:      * Event code.
 54:      *
 55:      * @param callable $handler
 56:      * The name or definition of the handler function. otherwise false.
 57:      *
 58:      * @return void
 59:      *
 60:      * @throws \Exception
 61:      * It might throw an exception in the case of any errors.
 62:      *
 63:      * @see IEventManager::addHandler()
 64:      * @see IEventManager::deleteHandlers()
 65:      * @see IEventManager::deleteAllHandlers()
 66:      *
 67:      * @author Oleg Schildt
 68:      */
 69:     public function deleteHandler(string $event, callable $handler): void;
 70: 
 71:     /**
 72:      * Deletes all handlers of an event.
 73:      *
 74:      * @param string $event
 75:      * Event code.
 76:      *
 77:      * @return void
 78:      *
 79:      * @throws \Exception
 80:      * It might throw an exception in the case of any errors.
 81:      *
 82:      * @see IEventManager::addHandler()
 83:      * @see IEventManager::deleteHandler()
 84:      * @see IEventManager::deleteAllHandlers()
 85:      *
 86:      * @author Oleg Schildt
 87:      */
 88:     public function deleteHandlers(string $event): void;
 89: 
 90:     /**
 91:      * Deletes all handlers of all events.
 92:      *
 93:      * @return void
 94:      *
 95:      * @see IEventManager::addHandler()
 96:      * @see IEventManager::deleteHandler()
 97:      * @see IEventManager::deleteHandlers()
 98:      *
 99:      * @author Oleg Schildt
100:      */
101:     public function deleteAllHandlers(): void;
102: 
103:     /**
104:      * Suspends an event.
105:      *
106:      * If an event is suspended, its handlers are not called when the event is fired.
107:      *
108:      * @param string $event
109:      * Event code.
110:      *
111:      * @return void
112:      *
113:      * @throws \Exception
114:      * It might throw an exception in the case of any errors.
115:      *
116:      * @see IEventManager::resumeEvent()
117:      * @see IEventManager::resumeAllEvents()
118:      *
119:      * @author Oleg Schildt
120:      */
121:     public function suspendEvent(string $event): void;
122: 
123:     /**
124:      * Resumes a previously suspended event.
125:      *
126:      * @param string $event
127:      * Event code.
128:      *
129:      * @return void
130:      *
131:      * @throws \Exception
132:      * It might throw an exception in the case of any errors.
133:      *
134:      * @see IEventManager::suspendEvent()
135:      * @see IEventManager::resumeAllEvents()
136:      *
137:      * @author Oleg Schildt
138:      */
139:     public function resumeEvent(string $event): void;
140: 
141:     /**
142:      * Resumes all previously suspended events.
143:      *
144:      * @return void
145:      *
146:      * @see IEventManager::suspendEvent()
147:      * @see IEventManager::resumeEvent()
148:      *
149:      * @author Oleg Schildt
150:      */
151:     public function resumeAllEvents(): void;
152: 
153:     /**
154:      * Fires and event.
155:      *
156:      * @param string $event
157:      * Event code.
158:      *
159:      * @param array $parameters
160:      * Event code.
161:      *
162:      * @return int
163:      * Should return number of the handlers called for this event.
164:      *
165:      * @throws \Exception
166:      * It might throw an exception in the case of any errors.
167:      *
168:      * @author Oleg Schildt
169:      */
170:     public function fireEvent(string $event, array $parameters): int;
171: } // IEventManager