N°4756 - Ease extensibility for CRUD operations : Event Service - move event description to an object

2026-05-18 23:08:46 +02:00 · 2022-12-13 11:55:05 +01:00
parent 432579657c
commit deb6d1fd9a
7 changed files with 312 additions and 18 deletions
--- a/application/applicationevents.class.inc.php
+++ b/application/applicationevents.class.inc.php
@@ -5,13 +5,14 @@
 * @license     http://opensource.org/licenses/AGPL-3.0
 */

+use Combodo\iTop\Service\Description\EventDescription;
 use Combodo\iTop\Service\EventService;
 use Combodo\iTop\Service\iEventServiceSetup;

 class ApplicationEvents implements iEventServiceSetup
 {
 	// Startup events
-	const APPLICATION_EVENT_REQUEST_RECEIVED = 'APPLICATION_EVENT_REQUEST_RECEIVED';
+	const APPLICATION_EVENT_REQUEST_RECEIVED  = 'APPLICATION_EVENT_REQUEST_RECEIVED';
 	const APPLICATION_EVENT_METAMODEL_STARTED = 'APPLICATION_EVENT_METAMODEL_STARTED';

 	/**
@@ -19,11 +20,19 @@ class ApplicationEvents implements iEventServiceSetup
 	 */
 	public function RegisterEventsAndListeners()
 	{
-		EventService::RegisterEvent(self::APPLICATION_EVENT_REQUEST_RECEIVED, [
-			'description' => 'A request was received from the network, at this point only the session is started, the configuration is not even loaded',
-		], 'application');
-		EventService::RegisterEvent(self::APPLICATION_EVENT_METAMODEL_STARTED, [
-			'description' => 'The MetaModel is fully started',
-		], 'application');
+		EventService::RegisterEvent(new EventDescription(
+			self::APPLICATION_EVENT_REQUEST_RECEIVED,
+			null,
+			'A request was received from the network, at this point only the session is started, the configuration is not even loaded',
+			'',
+			[],
+			'application'));
+		EventService::RegisterEvent(new EventDescription(
+			self::APPLICATION_EVENT_METAMODEL_STARTED,
+			null,
+			'The MetaModel is fully started',
+			'',
+			[],
+			'application'));
 	}
 }
--- a/lib/composer/autoload_classmap.php
+++ b/lib/composer/autoload_classmap.php
@@ -428,6 +428,8 @@ return array(
    'Combodo\\iTop\\Renderer\\FormRenderer' => $baseDir . '/sources/Renderer/FormRenderer.php',
    'Combodo\\iTop\\Renderer\\RenderingOutput' => $baseDir . '/sources/Renderer/RenderingOutput.php',
    'Combodo\\iTop\\Router\\Router' => $baseDir . '/sources/Router/Router.php',
+    'Combodo\\iTop\\Service\\Description\\EventDataDescription' => $baseDir . '/sources/Application/Service/Description/EventDataDescription.php',
+    'Combodo\\iTop\\Service\\Description\\EventDescription' => $baseDir . '/sources/Application/Service/Description/EventDescription.php',
    'Combodo\\iTop\\Service\\EventData' => $baseDir . '/sources/Application/Service/EventData.php',
    'Combodo\\iTop\\Service\\EventHelper' => $baseDir . '/sources/Application/Service/EventHelper.php',
    'Combodo\\iTop\\Service\\EventService' => $baseDir . '/sources/Application/Service/EventService.php',
--- a/lib/composer/autoload_static.php
+++ b/lib/composer/autoload_static.php
@@ -793,6 +793,8 @@ class ComposerStaticInit7f81b4a2a468a061c306af5e447a9a9f
        'Combodo\\iTop\\Renderer\\FormRenderer' => __DIR__ . '/../..' . '/sources/Renderer/FormRenderer.php',
        'Combodo\\iTop\\Renderer\\RenderingOutput' => __DIR__ . '/../..' . '/sources/Renderer/RenderingOutput.php',
        'Combodo\\iTop\\Router\\Router' => __DIR__ . '/../..' . '/sources/Router/Router.php',
+        'Combodo\\iTop\\Service\\Description\\EventDataDescription' => __DIR__ . '/../..' . '/sources/Application/Service/Description/EventDataDescription.php',
+        'Combodo\\iTop\\Service\\Description\\EventDescription' => __DIR__ . '/../..' . '/sources/Application/Service/Description/EventDescription.php',
        'Combodo\\iTop\\Service\\EventData' => __DIR__ . '/../..' . '/sources/Application/Service/EventData.php',
        'Combodo\\iTop\\Service\\EventHelper' => __DIR__ . '/../..' . '/sources/Application/Service/EventHelper.php',
        'Combodo\\iTop\\Service\\EventService' => __DIR__ . '/../..' . '/sources/Application/Service/EventService.php',
--- a/setup/compiler.class.inc.php
+++ b/setup/compiler.class.inc.php
@@ -1097,11 +1097,65 @@ EOF
 		$sName = $oEvent->getAttribute('id');
 		$aEventDescription = DesignElement::ToArray($oEvent);

-		$sDescription = var_export($aEventDescription, true);
+		// array (
+		//  'description' => 'An object insert in the database has been requested. All changes to the object will be persisted automatically.',
+		//  'sources' =>
+		//  array (
+		//    'cmdbAbstractObject' => 'cmdbAbstractObject',
+		//  ),
+		//  'replaces' => 'DBObject::OnInsert',
+		//  'event_data' =>
+		//  array (
+		//    'object' =>
+		//    array (
+		//      'description' => 'The object inserted',
+		//      'type' => 'DBObject',
+		//    ),
+		//    'debug_info' =>
+		//    array (
+		//      'description' => 'Debug string',
+		//      'type' => 'string',
+		//    ),
+		//  ),
+		// )
 		$sConstant = $sName;

 		$sOutput = "const $sConstant = '$sName';\n";
-		$sOutput .= "Combodo\iTop\Service\EventService::RegisterEvent($sName, $sDescription, '$sModuleName');\n";
+		$sOutput .= "\Combodo\iTop\Service\EventService::RegisterEvent(\n";
+		$sOutput .= "  new \Combodo\iTop\Service\Description\EventDescription(\n";
+		//$sEventName
+		$sOutput .= "    '$sName',\n";
+		//$mEventSources
+		$sOutput .= "    [\n";
+		foreach ($aEventDescription['sources'] as $sSourceId => $sSourceName) {
+			$sOutput .= "        '$sSourceId' => '$sSourceName',\n";
+		}
+		$sOutput .= "    ],\n";
+		// $sDescription
+		$sOutput .= "    '{$aEventDescription['description']}',\n";
+		// $sReplaces
+		if (isset($aEventDescription['replaces'])) {
+			$sOutput .= "    '{$aEventDescription['replaces']}',\n";
+		} else {
+			$sOutput .= "    '',\n";
+		}
+		// $aEventDataDescription
+		$sOutput .= "    [\n";
+		foreach ($aEventDescription['event_data'] as $sEventDataName => $aEventDataDescription) {
+			$sEventDataDesc = $aEventDataDescription['description'];
+			$sEventDataType = $aEventDataDescription['type'];
+ 			$sOutput .= "        new \Combodo\iTop\Service\Description\EventDataDescription(\n";
+			$sOutput .= "            '$sEventDataName',\n";
+			$sOutput .= "            '$sEventDataDesc',\n";
+			$sOutput .= "            '$sEventDataType',\n";
+			$sOutput .= "        ),\n";
+		}
+		$sOutput .= "    ],\n";
+		// $sModule
+		$sOutput .= "    '$sModuleName'\n";
+		$sOutput .= "  )\n";
+		$sOutput .= ");\n";
+

 		return $sOutput;
 	}
--- a/sources/Application/Service/Description/EventDataDescription.php
+++ b/sources/Application/Service/Description/EventDataDescription.php
@@ -0,0 +1,83 @@
+<?php
+/*
+ * @copyright   Copyright (C) 2010-2022 Combodo SARL
+ * @license     http://opensource.org/licenses/AGPL-3.0
+ */
+
+namespace Combodo\iTop\Service\Description;
+
+/**
+ * Description of the data given with an event when registering
+ *
+ * @api
+ * @since 3.1.0
+ */
+class EventDataDescription
+{
+	private string $sName;
+	private string $sDescription;
+	private string $sType;
+
+	/**
+	 * Create a data description
+	 *
+	 * @api
+	 * @param string $sName Name of the parameter
+	 * @param string $sDescription  Description of the parameter
+	 * @param string $sType Type of the parameter
+	 */
+	public function __construct(string $sName, string $sDescription, string $sType)
+	{
+		$this->sName = $sName;
+		$this->sDescription = $sDescription;
+		$this->sType = $sType;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function GetName(): string
+	{
+		return $this->sName;
+	}
+
+	/**
+	 * @param string $sName
+	 */
+	public function SetName(string $sName): void
+	{
+		$this->sName = $sName;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function GetDescription(): string
+	{
+		return $this->sDescription;
+	}
+
+	/**
+	 * @param string $sDescription
+	 */
+	public function SetDescription(string $sDescription): void
+	{
+		$this->sDescription = $sDescription;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function GetType(): string
+	{
+		return $this->sType;
+	}
+
+	/**
+	 * @param string $sType
+	 */
+	public function SetType(string $sType): void
+	{
+		$this->sType = $sType;
+	}
+}
--- a/sources/Application/Service/Description/EventDescription.php
+++ b/sources/Application/Service/Description/EventDescription.php
@@ -0,0 +1,142 @@
+<?php
+/*
+ * @copyright   Copyright (C) 2010-2022 Combodo SARL
+ * @license     http://opensource.org/licenses/AGPL-3.0
+ */
+
+namespace Combodo\iTop\Service\Description;
+
+/**
+ * Description of an event when registering
+ *
+ * @api
+ * @since 3.1.0
+ */
+class EventDescription
+{
+	private string $sEventName;
+	/** @var string[]|string|null  */
+	private $mEventSources;
+	private string $sDescription;
+	private string $sReplaces;
+	/** @var \Combodo\iTop\Service\Description\EventDataDescription[]  */
+	private array $aEventDataDescription;
+	private string $sModule;
+
+	/**
+	 * Create a description for an event
+	 *
+	 * @api
+	 * @param string $sEventName Name of the described event
+	 * @param string|string[]|null $mEventSources Source(s) for this event (can be the root class for CRUD events)
+	 * @param string $sDescription Description of the event
+	 * @param string $sReplaces In case this event obsoletes previous extensibility functions
+	 * @param \Combodo\iTop\Service\Description\EventDataDescription[] $aEventDataDescription Description of the data associated with this event
+	 * @param string $sModule iTop Module name where the event is defined
+	 */
+	public function __construct(string $sEventName, $mEventSources, string $sDescription, string $sReplaces, array $aEventDataDescription, string $sModule)
+	{
+		$this->sEventName = $sEventName;
+		$this->mEventSources = $mEventSources;
+		$this->sDescription = $sDescription;
+		$this->sReplaces = $sReplaces;
+		$this->aEventDataDescription = $aEventDataDescription;
+		$this->sModule = $sModule;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function GetEventName(): string
+	{
+		return $this->sEventName;
+	}
+
+	/**
+	 * @param string $sEventName
+	 */
+	public function SetEventName(string $sEventName): void
+	{
+		$this->sEventName = $sEventName;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function GetDescription(): string
+	{
+		return $this->sDescription;
+	}
+
+	/**
+	 * @param string $sDescription
+	 */
+	public function SetDescription(string $sDescription): void
+	{
+		$this->sDescription = $sDescription;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function GetReplaces(): string
+	{
+		return $this->sReplaces;
+	}
+
+	/**
+	 * @param string $sReplaces
+	 */
+	public function SetReplaces(string $sReplaces): void
+	{
+		$this->sReplaces = $sReplaces;
+	}
+
+	/**
+	 * @return array
+	 */
+	public function GetEventDataDescription(): array
+	{
+		return $this->aEventDataDescription;
+	}
+
+	/**
+	 * @param \Combodo\iTop\Service\Description\EventDataDescription[]s $aEventDataDescription
+	 */
+	public function SetEventDataDescription(array $aEventDataDescription): void
+	{
+		$this->aEventDataDescription = $aEventDataDescription;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function GetModule(): string
+	{
+		return $this->sModule;
+	}
+
+	/**
+	 * @param string $sModule
+	 */
+	public function SetModule(string $sModule): void
+	{
+		$this->sModule = $sModule;
+	}
+
+	/**
+	 * @return string|string[]|null
+	 */
+	public function GetEventSources()
+	{
+		return $this->mEventSources;
+	}
+
+	/**
+	 * @param string|string[]|null $mEventSources
+	 */
+	public function SetEventSources($mEventSources): void
+	{
+		$this->mEventSources = $mEventSources;
+	}
+}
--- a/sources/Application/Service/EventService.php
+++ b/sources/Application/Service/EventService.php
@@ -7,6 +7,7 @@
 namespace Combodo\iTop\Service;

 use Closure;
+use Combodo\iTop\Service\Description\EventDescription;
 use ContextTag;
 use CoreException;
 use Exception;
@@ -281,24 +282,25 @@ class EventService
 	 * This step is mandatory before firing an event.
 	 *
 	 * @api
-	 * @param string $sEvent
-	 * @param array $aDescription
-	 * @param string $sModule
+	 * @param \Combodo\iTop\Service\Description\EventDescription $oEventDescription
 	 *
 	 * @return void
 	 */
-	public static function RegisterEvent(string $sEvent, array $aDescription, string $sModule)
+	public static function RegisterEvent(EventDescription $oEventDescription)
 	{
+		$sEvent = $oEventDescription->GetEventName();
+		$sModule = $oEventDescription->GetModule();
 		if (self::IsEventRegistered($sEvent)) {
 			$sPrevious = self::$aEventDescription[$sEvent]['module'];
 			EventHelper::Warning("The Event $sEvent defined by $sModule has already been defined in $sPrevious, check your delta");
+
 			return;
 		}

 		self::$aEventDescription[$sEvent] = [
-			'name'=> $sEvent,
-			'description' => $aDescription,
-			'module' => $sModule,
+			'name'        => $sEvent,
+			'description' => $oEventDescription,
+			'module'      => $sModule,
 		];
 	}

@@ -307,8 +309,8 @@ class EventService
 		$aRes = [];
 		$oClass = new ReflectionClass($sClass);
 		foreach (self::$aEventDescription as $sEvent => $aEventInfo) {
-			if (isset($aEventInfo['description']['sources'])) {
-				foreach ($aEventInfo['description']['sources'] as $sSource) {
+			if (is_array($aEventInfo['description']->GetSources())) {
+				foreach ($aEventInfo['description']->GetSources() as $sSource) {
 					if ($sClass == $sSource || $oClass->isSubclassOf($sSource)) {
 						$aRes[$sEvent] = $aEventInfo;
 					}