N°4756 - Ease extensibility for CRUD operations : Event Service - documentation

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()
 	{

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

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();