N°7629 Deprecate utils::GetClassesForInterface in favor of InterfaceDiscovery::FindItopClasses

Improve caching strategy and robustness

sources/Service/Cache/DataModelDependantCache.php

@@ -0,0 +1,155 @@
+<?php
+
+namespace Combodo\iTop\Service\Cache;
+
+use Exception;
+use SetupUtils;
+use utils;
+
+/**
+ * A simple cache service that stores data in files
+ * - No TTL: automatically invalidated when iTop is recompiled
+ * - Concurrent access safe
+ *
+ * @since 3.2.0
+ * @experimental The API may change in future versions
+ * @internal DO NOT use in extensions until it is declared stable
+ */
+class DataModelDependantCache
+{
+	private static DataModelDependantCache $oInstance;
+
+	public static function GetInstance(): DataModelDependantCache
+	{
+		if (!isset(self::$oInstance))
+		{
+			self::$oInstance = new DataModelDependantCache(utils::GetCachePath());
+		}
+		return self::$oInstance;
+	}
+
+	private ?string $sStorageRootDir; // Nullable for test purposes
+
+	private function __construct($sStorageRootDir)
+	{
+		$this->sStorageRootDir = $sStorageRootDir;
+	}
+
+	/**
+	 * @param string $sPool
+	 * @param string $sKey Any characters allowed, special characters equivalent to '_'
+	 * @param mixed $value Any primitive type, immutable object, or array of such. NULL is not allowed.
+	 * @param array $aMoreInfo Key-value pairs to store additional information about the cache entry
+	 *
+	 * @return void
+	 * @throws \Exception
+	 */
+	public function Store(string $sPool, string $sKey, mixed $value, array $aMoreInfo = []): void
+	{
+		if(is_null($value)) {
+			// NULL cannot be stored as it collides with Fetch() returning NULL when the key does not exist
+			throw new Exception('Cannot store NULL in the cache');
+		}
+		$sCacheFileName = $this->MakeCacheFileName($sPool, $sKey);
+		SetupUtils::builddir(dirname($sCacheFileName));
+
+		$sMoreInfo = '';
+		foreach ($aMoreInfo as $sKey => $sValue) {
+			$sMoreInfo .= "\n// $sKey: $sValue";
+		}
+		$sCacheContent = "<?php $sMoreInfo\nreturn ".var_export($value, true).";";
+		file_put_contents($sCacheFileName, $sCacheContent, LOCK_EX);
+	}
+
+	/**
+	 * Fetch the cached values for a given key, in the current pool
+	 *
+	 * @param string $sPool
+	 * @param string $sKey
+	 *
+	 * @return mixed|null returns null if the key does not exist in the current pool
+	 */
+	public function Fetch(string $sPool, string $sKey): mixed
+	{
+		$sCacheFileName = $this->MakeCacheFileName($sPool, $sKey);
+		if (!is_file($sCacheFileName)) return null;
+		return include $sCacheFileName;
+	}
+
+	/**
+	 * @param string $sPool
+	 * @param string $sKey
+	 *
+	 * @return bool
+	 */
+	public function HasEntry(string $sPool, string $sKey): bool
+	{
+		return file_exists($this->MakeCacheFileName($sPool, $sKey));
+	}
+
+	/**
+	 * Get the last modification time of a cache entry
+	 *
+	 * @param string $sPool
+	 * @param string $sKey
+	 *
+	 * @return int|null Unix timestamp or null if the entry doesn't exist
+	 */
+	public function GetEntryModificationTime(string $sPool, string $sKey): int|null
+	{
+		$sCacheFileName = $this->MakeCacheFileName($sPool, $sKey);
+		if (!is_file($sCacheFileName)) return null;
+		return filemtime($sCacheFileName);
+	}
+	/**
+	 * Remove an entry from the current pool
+	 *
+	 * @param string $sPool
+	 * @param string $sKey
+	 *
+	 * @return void
+	 */
+	public function DeleteItem(string $sPool, string $sKey): void
+	{
+		$sCacheFileName = $this->MakeCacheFileName($sPool, $sKey);
+		if (is_file($sCacheFileName)) {
+			unlink($sCacheFileName);
+		}
+	}
+
+	/**
+	 * Remove all entries from the current pool
+	 *
+	 * @param string $sPool
+	 *
+	 * @return void
+	 * @throws Exception
+	 */
+	public function Clear(string $sPool): void
+	{
+		$sPoolDir = $this->MakePoolDirPath($sPool);
+		if (is_dir($sPoolDir)) {
+			SetupUtils::tidydir($sPoolDir);
+		}
+	}
+
+	private function MakeCacheFileName(string $sPool, string $sKey): string
+	{
+		// Replace all characters that are not alphanumeric by '_'
+		$sKey = preg_replace('/[^a-zA-Z0-9]/', '_', $sKey);
+
+		return $this->MakePoolDirPath($sPool).$sKey.'.php';
+	}
+
+	private function MakePoolDirPath(string $sPool): string
+	{
+		return $this->GetStorageRootDir()."/$sPool/";
+	}
+
+	/** Overridable for testing purposes */
+	protected function GetStorageRootDir(): string
+	{
+		// Could be forced by tests
+		return $this->sStorageRootDir ?? utils::GetCachePath();
+	}
+}

sources/Service/Events/EventService.php

@@ -8,6 +8,7 @@ namespace Combodo\iTop\Service\Events;
 
 use Closure;
 use Combodo\iTop\Service\Events\Description\EventDescription;
+use Combodo\iTop\Service\InterfaceDiscovery\InterfaceDiscovery;
 use Combodo\iTop\Service\Module\ModuleService;
 use ContextTag;
 use CoreException;
@@ -43,9 +44,9 @@ final class EventService
 	 */
 	public static function InitService()
 	{
-		$aEventServiceSetup = utils::GetClassesForInterface(iEventServiceSetup::class, '', ['[\\\\/]lib[\\\\/]', '[\\\\/]node_modules[\\\\/]', '[\\\\/]test[\\\\/]']);
+		$aEventServiceSetup = InterfaceDiscovery::GetInstance()->FindItopClasses(iEventServiceSetup::class);
 		foreach ($aEventServiceSetup as $sEventServiceSetupClass) {
-			/** @var \Combodo\iTop\Service\Events\iEventServiceSetup $oEventServiceSetup */
+			/** @var iEventServiceSetup $oEventServiceSetup */
 			$oEventServiceSetup = new $sEventServiceSetupClass();
 			$oEventServiceSetup->RegisterEventsAndListeners();
 		}

sources/Service/InterfaceDiscovery/InterfaceDiscovery.php

@@ -0,0 +1,206 @@
+<?php
+
+namespace Combodo\iTop\Service\InterfaceDiscovery;
+
+use Combodo\iTop\Service\Cache\DataModelDependantCache;
+use Exception;
+use IssueLog;
+use LogChannels;
+use ReflectionClass;
+use utils;
+
+class InterfaceDiscovery
+{
+	private static InterfaceDiscovery $oInstance;
+	private ?array $aForcedClassMap = null; // For testing purposes
+
+	private function __construct()
+	{
+	}
+
+	public static function GetInstance(): InterfaceDiscovery
+	{
+		if (!isset(self::$oInstance))
+		{
+			self::$oInstance = new InterfaceDiscovery();
+		}
+		return self::$oInstance;
+	}
+
+	/**
+	 * Find the ITOP classes implementing a given interface. The returned classes have the following properties:
+	 * - They can be instantiated
+	 * - They are not aliases
+	 *
+	 * @param string $sInterface Fully qualified interface name
+	 * @param array|null $aAdditionalExcludedPaths Optional list of paths to exclude from the search (partial names allowed, case sensitive, use / as separator)
+	 *
+	 * @return array of fully qualified class names
+	 */
+	public function FindItopClasses(string $sInterface, ?array $aAdditionalExcludedPaths = null): array
+	{
+		if (is_null($aAdditionalExcludedPaths)) {
+			return $this->FindClasses($sInterface, ['/lib/', '/node_modules/', '/test/', '/tests/']);
+		}
+
+		$aExcludedPaths = array_merge(['/lib/', '/node_modules/', '/test/', '/tests/'], $aAdditionalExcludedPaths);
+		return $this->FindClasses($sInterface, $aExcludedPaths);
+	}
+
+	private function FindClasses(string $sInterface, array $aExcludedPaths = []): array
+	{
+		$sCacheUniqueKey = $this->MakeCacheKey($sInterface, $aExcludedPaths);
+		if ($this->IsCacheValid($sCacheUniqueKey)) {
+			return $this->ReadClassesFromCache($sCacheUniqueKey);
+		}
+
+		$sExcludedPathsRegExp = $this->GetExcludedPathsRegExp($aExcludedPaths);
+		$aMatchingClasses = [];
+		foreach ($this->GetCandidateClasses() as $sPHPClass => $sOptionalPHPFile) {
+			if (!$this->IsValidPHPFile($sOptionalPHPFile, $sExcludedPathsRegExp)) {
+				continue;
+			}
+
+			if ($this->IsInterfaceImplementation($sPHPClass, $sInterface)) {
+				$aMatchingClasses[] = $sPHPClass;
+			}
+		}
+
+		$this->SaveClassesToCache($sCacheUniqueKey, $aMatchingClasses, ['Interface' => $sInterface, 'Excluded paths' => implode(',', $aExcludedPaths)]);
+
+		return $aMatchingClasses;
+	}
+	private function GetAutoloadClassMaps(): array
+	{
+		$oCacheService = DataModelDependantCache::GetInstance();
+
+		$aAutoloadClassMaps = $oCacheService->Fetch('InterfaceDiscovery', 'autoload_classmaps');
+		if ($aAutoloadClassMaps !== null) {
+			return $aAutoloadClassMaps;
+		}
+
+		// guess all the autoload class maps from the extensions
+		$aAutoloadClassMaps = glob(APPROOT.'env-'.utils::GetCurrentEnvironment().'/*/vendor/composer/autoload_classmap.php');
+		$aAutoloadClassMaps[] = APPROOT.'lib/composer/autoload_classmap.php';
+
+		$oCacheService->Store('InterfaceDiscovery', 'autoload_classmaps', $aAutoloadClassMaps);
+		return $aAutoloadClassMaps;
+	}
+
+	private function IsInterfaceImplementation(string $sPHPClass, string $sInterface): bool
+	{
+		try {
+			$oRefClass = new ReflectionClass($sPHPClass);
+		} catch (Exception $e) {
+			return false;
+		}
+
+		if (!$oRefClass->implementsInterface($sInterface)) return false;
+		if ($oRefClass->isInterface()) return false;
+		if ($oRefClass->isAbstract()) return false;
+		if ($oRefClass->isTrait()) return false;
+		if ($oRefClass->getName() !== $sPHPClass) return false; // Skip aliases
+
+		return true;
+	}
+
+	protected function GetCandidateClasses(): array
+	{
+		$aClassMap = [];
+		$aAutoloaderErrors = [];
+		if ($this->aForcedClassMap !== null) {
+			$aClassMap = $this->aForcedClassMap;
+		}
+		else {
+			foreach ($this->GetAutoloadClassMaps() as $sAutoloadFile) {
+				if (false === utils::RealPath($sAutoloadFile, APPROOT)) {
+					// can happen when we still have the autoloader symlink in env-*, but it points to a file that no longer exists
+					$aAutoloaderErrors[] = $sAutoloadFile;
+					continue;
+				}
+				$aTmpClassMap = include $sAutoloadFile;
+				/** @noinspection SlowArrayOperationsInLoopInspection we are getting an associative array so the documented workarounds cannot be used */
+				$aClassMap = array_merge($aClassMap, $aTmpClassMap);
+			}
+			if (count($aAutoloaderErrors) > 0) {
+				IssueLog::Debug(
+					__METHOD__." cannot load some of the autoloader files",
+					LogChannels::CORE,
+					['autoloader_errors' => $aAutoloaderErrors]
+				);
+			}
+
+			// Add already loaded classes
+			$aCurrentClasses = array_fill_keys(get_declared_classes(), '');
+			$aClassMap = array_merge($aCurrentClasses, $aClassMap);
+		}
+
+		return $aClassMap;
+	}
+
+	private function IsValidPHPFile(string $sOptionalPHPFile, ?string $sExcludedPathsRegExp): bool
+	{
+		if ($sOptionalPHPFile === '') return true;
+
+		$sOptionalPHPFile = utils::LocalPath($sOptionalPHPFile);
+		if ($sOptionalPHPFile === false) return false;
+
+		if (is_null($sExcludedPathsRegExp)) return true;
+
+		if (preg_match($sExcludedPathsRegExp, '/'.$sOptionalPHPFile) === 1) {
+			return false;
+		}
+
+		return true;
+	}
+
+	private function IsCacheValid(string $sKey): bool
+	{
+		if ($this->aForcedClassMap !== null) return false;
+
+		$oCacheService = DataModelDependantCache::GetInstance();
+
+		if (!$oCacheService->HasEntry('InterfaceDiscovery', $sKey)) return false;
+
+		if (!utils::IsDevelopmentEnvironment()) return true;
+
+		// On development environment, we check the cache validity by comparing the cache file with the autoload_classmap files
+		$iCacheTime = $oCacheService->GetEntryModificationTime('InterfaceDiscovery', $sKey);
+		foreach($this->GetAutoloadClassMaps() as $sSourceFile) {
+			$iSourceTime = filemtime($sSourceFile);
+			if ($iSourceTime > $iCacheTime) return false;
+		}
+		return true;
+	}
+
+	public function ReadClassesFromCache(string $sKey): array
+	{
+		$oCacheService = DataModelDependantCache::GetInstance();
+		return $oCacheService->Fetch('InterfaceDiscovery', $sKey);
+	}
+
+	protected function SaveClassesToCache(string $sKey, array $aMatchingClasses, array $aMoreInfo): void
+	{
+		if ($this->aForcedClassMap !== null) return;
+
+		$oCacheService = DataModelDependantCache::GetInstance();
+		$oCacheService->Store('InterfaceDiscovery', $sKey, $aMatchingClasses, $aMoreInfo);
+	}
+
+	private function GetExcludedPathsRegExp(array $aExcludedPaths) : ?string
+	{
+		if (count($aExcludedPaths) == 0) return null;
+
+		$aExcludedPathRegExps = array_map(function($sPath) {
+			return preg_quote($sPath, '#');
+		}, $aExcludedPaths);
+
+		return '#'.implode('|', $aExcludedPathRegExps).'#';
+	}
+
+	protected function MakeCacheKey(string $sInterface, array $aExcludedPaths): string
+	{
+		if (count($aExcludedPaths) == 0) return $sInterface;
+		return md5($sInterface.':'.implode(',', $aExcludedPaths));
+	}
+}

sources/Service/Router/Router.php

@@ -6,6 +6,8 @@
 
 namespace Combodo\iTop\Service\Router;
 
+use Combodo\iTop\Controller\iController;
+use Combodo\iTop\Service\InterfaceDiscovery\InterfaceDiscovery;
 use Combodo\iTop\Service\Router\Exception\RouteNotFoundException;
 use ReflectionClass;
 use ReflectionMethod;
@@ -174,7 +176,7 @@ class Router
 
 		// If no cache, force to re-scan for routes
 		if (count($aRoutes) === 0) {
-			foreach (utils::GetClassesForInterface('Combodo\iTop\Controller\iController', '', ['[\\\\/]lib[\\\\/]', '[\\\\/]node_modules[\\\\/]', '[\\\\/]test[\\\\/]']) as $sControllerFQCN) {
+			foreach (InterfaceDiscovery::GetInstance()->FindItopClasses(iController::class) as $sControllerFQCN) {
 				$sRouteNamespace = $sControllerFQCN::ROUTE_NAMESPACE;
 				// Ignore controller with no namespace
 				if (is_null($sRouteNamespace)) {