diff --git a/sources/Application/Service/EventData.php b/sources/Application/Service/EventData.php index d8e39e1a1..a5edf6bd7 100644 --- a/sources/Application/Service/EventData.php +++ b/sources/Application/Service/EventData.php @@ -11,7 +11,9 @@ namespace Combodo\iTop\Service; * Data given to the Event Service callbacks * Class EventServiceData * + * @api * @package Combodo\iTop\Service + * @since 3.1.0 */ class EventData { @@ -23,9 +25,10 @@ class EventData /** * EventServiceData constructor. * - * @param string $sEvent - * @param string|array|null $mEventSource - * @param array $aEventData + * @api + * @param string $sEvent Event fired + * @param string|array|null $mEventSource Event source + * @param array $aEventData Event data for the listeners */ public function __construct(string $sEvent, $mEventSource = null, array $aEventData = []) { @@ -36,13 +39,24 @@ class EventData } /** - * @return string + * Get the event fired. + * + * @api + * @return string Event fired. */ public function GetEvent() { return $this->sEvent; } + /** + * Get any parameter from the data sent when firing the event. + * + * @api + * @param $sParam + * + * @return mixed|null Parameter given when firing the event. + */ public function Get($sParam) { if (is_array($this->aEventData) && isset($this->aEventData[$sParam])) { @@ -57,7 +71,10 @@ class EventData } /** - * @return mixed + * Get event source of fired event. + * + * @api + * @return mixed Source given when firing the event. */ public function GetEventSource() { @@ -65,7 +82,10 @@ class EventData } /** - * @return array + * Get all the data sent when firing the event. + * + * @api + * @return array All the data given when firing the event. */ public function GetEventData(): array { @@ -81,7 +101,11 @@ class EventData } /** - * @return mixed + * Get the data associated with the listener. + * The data were passed when registering the listener. + * + * @api + * @return mixed The data registered with the listener. */ public function GetCallbackData() { diff --git a/sources/Application/Service/EventService.php b/sources/Application/Service/EventService.php index 706d965e9..e65014d2e 100644 --- a/sources/Application/Service/EventService.php +++ b/sources/Application/Service/EventService.php @@ -14,12 +14,27 @@ use ExecutionKPI; use ReflectionClass; use utils; +/** + * Event driven extensibility. + * Inspired by [PSR-14: Event Dispatcher](https://www.php-fig.org/psr/psr-14). + * Adapted to iTop needs in terms of event filtering (using event source or context). + * + * @package Combodo\iTop\Service + * @api + * @since 3.1.0 + */ class EventService { private static $aEventListeners = []; private static $iEventIdCounter = 0; private static $aEventDescription = []; + /** + * Initialize the Event Service. This is called by iTop. + * + * @internal + * @return void + */ public static function InitService() { self::$aEventListeners = []; @@ -38,6 +53,7 @@ class EventService /** * Register a callback for a specific event * + * @api * @param string $sEvent corresponding event * @param callable $callback The callback to call * @param array|string|null $sEventSource event filtering depending on the source of the event @@ -45,7 +61,7 @@ class EventService * @param array|string|null $context context filter * @param float $fPriority optional priority for callback order * - * @return string Id of the registration (used for unregistering) + * @return string Id of the registration * */ public static function RegisterListener(string $sEvent, callable $callback, $sEventSource = null, $aCallbackData = [], $context = null, float $fPriority = 0.0, $sModuleId = ''): string @@ -96,6 +112,7 @@ class EventService /** * Fire an event. Call all the callbacks registered for this event. * + * @api * @param \Combodo\iTop\Service\EventData $oEventData * * @throws \Exception from the callback @@ -213,7 +230,7 @@ class EventService } /** - * Unregister an event + * Unregister all the listeners for an event * * @param string $sEvent event to unregister */ @@ -259,6 +276,11 @@ class EventService } /** + * Register an event. + * This allows to describe all the events available. + * This step is mandatory before firing an event. + * + * @api * @param string $sEvent * @param array $aDescription * @param string $sModule @@ -297,20 +319,11 @@ class EventService return $aRes; } - // Intentionally duplicated from SetupUtils, not yet loaded when RegisterEvent is called - private static function FromCamelCase($sInput) { - $sPattern = '!([A-Z][A-Z0-9]*(?=$|[A-Z][a-z0-9])|[A-Za-z][a-z0-9]+)!'; - preg_match_all($sPattern, $sInput, $aMatches); - $aRet = $aMatches[0]; - foreach ($aRet as &$sMatch) { - $sMatch = $sMatch == strtoupper($sMatch) ? - strtolower($sMatch) : - lcfirst($sMatch); - } - return implode('_', $aRet); - } - /** + * Check is an event is already registered. + * Can be used to avoid exception when firing an unregistered event. + * + * @api * @param string $sEvent * * @return bool diff --git a/sources/Application/Service/iEventServiceSetup.php b/sources/Application/Service/iEventServiceSetup.php index 070174020..b3c395176 100644 --- a/sources/Application/Service/iEventServiceSetup.php +++ b/sources/Application/Service/iEventServiceSetup.php @@ -9,12 +9,16 @@ namespace Combodo\iTop\Service; /** * Interface to implement in order to register the events and listeners * + * @api + * @package Combodo\iTop\Service * @since 3.1.0 */ interface iEventServiceSetup { /** * Extension point to register the events and events listeners + * + * @api * @return void */ public function RegisterEventsAndListeners();