N°9553 upload localised structural data (#917)

* Helper for loading XML localized data during Setup
* Refactor existing code
* Add new localized structural data

setup/moduleinstaller.class.inc.php

@@ -309,4 +309,125 @@ abstract class ModuleInstallerAPI
 
 		CMDBSource::CacheReset($sOrigTable);
 	}
+
+	/**
+	 * @param \Config $oConfiguration
+	 * @param string $sPreviousVersion The previous version of the module (empty string will force the loading)
+	 * @param string $sCurrentVersion The current version of the module
+	 * @param string $sFirstLoadingVersion The first module version for which the data loading should be performed (e.g. '3.0.0')
+	 * @param string $sFilePattern The pattern of the file to load, with {{language_code}} as placeholder for the language code (e.g. 'data.sample.{{language_code}}.xml')
+	 *
+	 * @return void
+	 * @throws \ConfigException
+	 * @throws \CoreException
+	 * @throws \CoreUnexpectedValue
+	 */
+	public static function LoadLocalizedData(Config $oConfiguration, string $sPreviousVersion, string $sCurrentVersion, string $sFirstLoadingVersion, string $sFilePattern): void
+	{
+		self::AssertLoadLocalizedDataParametersAreValid($sPreviousVersion, $sCurrentVersion, $sFirstLoadingVersion, $sFilePattern);
+
+		// It's not very clear if it makes sense to test a particular version,
+		// as the loading mechanism checks object existence using reconc_keys
+		// and do not recreate them, nor update existing.
+		// Without test, new entries added to the data files, would be automatically loaded
+		if (($sPreviousVersion === '') ||
+			(version_compare($sPreviousVersion, $sCurrentVersion, '<')
+				&& version_compare($sPreviousVersion, $sFirstLoadingVersion, '<'))) {
+
+			// Note: There is an issue when upgrading, default language cannot be retrieved from the passed configuration, we have to read it from the disk
+			if (utils::IsNullOrEmptyString($sPreviousVersion)) {
+				// Fresh install
+				$sDefaultLanguage = $oConfiguration->GetDefaultLanguage();
+			} else {
+				// Upgrade
+				$sDefaultLanguage = utils::GetConfig(true)->GetDefaultLanguage();
+			}
+
+			$sFileName = self::GetLocalizedFileName($sDefaultLanguage, $sFilePattern);
+			if ($sFileName !== '') {
+				self::XMLFileLoad($sFileName);
+			}
+		}
+	}
+
+	/**
+	 * @throws \CoreUnexpectedValue
+	 */
+	private static function AssertLoadLocalizedDataParametersAreValid(string $sPreviousVersion, string $sCurrentVersion, string $sFirstLoadingVersion, string $sFilePattern): void
+	{
+		if (($sPreviousVersion !== '') && !self::IsValidLocalizedDataVersion($sPreviousVersion)) {
+			throw new CoreUnexpectedValue("LoadLocalizedData expects sPreviousVersion to be empty or match x.y[.z][-name], got '{$sPreviousVersion}'");
+		}
+
+		if (!self::IsValidLocalizedDataVersion($sCurrentVersion)) {
+			throw new CoreUnexpectedValue("LoadLocalizedData expects sCurrentVersion to match x.y[.z][-name], got '{$sCurrentVersion}'");
+		}
+
+		if (!self::IsValidLocalizedDataVersion($sFirstLoadingVersion)) {
+			throw new CoreUnexpectedValue("LoadLocalizedData expects sFirstLoadingVersion to match x.y[.z][-name], got '{$sFirstLoadingVersion}'");
+		}
+
+		if (utils::IsNullOrEmptyString($sFilePattern)) {
+			throw new CoreUnexpectedValue('LoadLocalizedData expects sFilePattern to be a non-empty string');
+		}
+
+		if (substr_count($sFilePattern, '{{language_code}}') !== 1) {
+			throw new CoreUnexpectedValue("LoadLocalizedData expects sFilePattern to contain the exact placeholder '{{language_code}}' exactly once");
+		}
+
+		$sParentDirectory = dirname($sFilePattern);
+		if (!is_dir($sParentDirectory)) {
+			throw new CoreUnexpectedValue("LoadLocalizedData expects sFilePattern parent directory to exist, got '{$sParentDirectory}'");
+		}
+	}
+
+	private static function IsValidLocalizedDataVersion(string $sVersion): bool
+	{
+		return (preg_match('/^\d+\.\d+(?:\.\d+)?(?:-[A-Za-z0-9]+)?$/', $sVersion) === 1);
+	}
+
+	/**
+	 * @param array|string $sFileName
+	 * @param \XMLDataLoader $oDataLoader
+	 *
+	 * @return void
+	 * @throws \Exception
+	 */
+	public static function XMLFileLoad(string $sFileName): void
+	{
+		if (!file_exists($sFileName)) {
+			throw new Exception("File $sFileName not found");
+		}
+		$oDataLoader = new XMLDataLoader();
+		CMDBObject::SetTrackInfo("Loading XML data from $sFileName");
+		$oMyChange = CMDBObject::GetCurrentChange();
+		SetupLog::Info("Loading objects in DB from file: $sFileName");
+		$oDataLoader->StartSession($oMyChange);
+		$oDataLoader->LoadFile($sFileName, false, true);
+		$oDataLoader->EndSession();
+	}
+
+	/**
+	 * @param string $sLanguage The language code to use for localization (e.g. 'EN US')
+	 * @param string $sFilePattern The full path+name of the file to localize, with {{language_code}} as placeholder for the language code (e.g. 'data.sample.{{language_code}}.xml')
+	 *
+	 * @return string The localized file name if found, or an empty string if not found
+	 * @throws \ConfigException
+	 * @throws \CoreException
+	 */
+	public static function GetLocalizedFileName($sLanguage, string $sFilePattern): string
+	{
+		$sLang = str_replace(' ', '_', strtolower($sLanguage));
+		$sFileName = str_replace('{{language_code}}', $sLang, $sFilePattern);
+		if (!file_exists($sFileName)) {
+			$sLang = 'en_us';
+			$sFileName = str_replace('{{language_code}}', $sLang, $sFilePattern);
+		}
+		if (file_exists($sFileName)) {
+			return $sFileName;
+		} else {
+			SetupLog::Warning("No data file matching the pattern $sFilePattern and language_code $sLang was found.");
+			return '';
+		}
+	}
 }