N°4897 - Add method to improve deprecated PHP API logs (eg. for \iPageUIExtension)

application/applicationextension.inc.php

@@ -1274,8 +1274,6 @@ abstract class AbstractPageUIExtension implements iPageUIExtension
 	 */
 	public function GetNorthPaneHtml(iTopWebPage $oPage)
 	{
-		DeprecatedCallsLog::NotifyDeprecatedPhpMethod('use iPageUIBlockExtension instead');
-
 		return '';
 	}
 
@@ -1284,8 +1282,6 @@ abstract class AbstractPageUIExtension implements iPageUIExtension
 	 */
 	public function GetSouthPaneHtml(iTopWebPage $oPage)
 	{
-		DeprecatedCallsLog::NotifyDeprecatedPhpMethod('use iPageUIBlockExtension instead');
-
 		return '';
 	}
 
@@ -1294,8 +1290,6 @@ abstract class AbstractPageUIExtension implements iPageUIExtension
 	 */
 	public function GetBannerHtml(iTopWebPage $oPage)
 	{
-		DeprecatedCallsLog::NotifyDeprecatedPhpMethod('use iPageUIBlockExtension instead');
-
 		return '';
 	}
 

core/log.class.inc.php

@@ -1090,6 +1090,11 @@ class DeadLockLog extends LogAPI
  */
 class DeprecatedCallsLog extends LogAPI
 {
+	/**
+	 * @var string
+	 * @since 3.2.0 N°4897
+	 */
+	public const ENUM_CHANNEL_PHP_API = 'deprecated-php-api';
 	public const ENUM_CHANNEL_PHP_METHOD = 'deprecated-php-method';
 	/**
 	 * @var string
@@ -1283,6 +1288,35 @@ class DeprecatedCallsLog extends LogAPI
 		static::Warning($sMessage, static::ENUM_CHANNEL_FILE);
 	}
 
+	/**
+	 * @param string $sImplementationClass Class implementing the deprecated API
+	 * @param string $sDeprecatedApi Class name of the deprecated API
+	 * @param string $sDeprecatedMethod Method name of the deprecated API
+	 * @param string|null $sAdditionalMessage Additional message, mostly used to explain what API to use instead
+	 *
+	 * @return void
+	 * @since 3.2.0 N°4897
+	 */
+	public static function NotifyDeprecatedPhpApi(string $sImplementationClass, string $sDeprecatedApi, string $sDeprecatedMethod, ?string $sAdditionalMessage = null): void
+	{
+		try {
+			if (!static::IsLogLevelEnabled(self::LEVEL_WARNING, self::ENUM_CHANNEL_PHP_API)) {
+				return;
+			}
+		}
+		catch (ConfigException $oException) {
+			return;
+		}
+
+		$sMessage = "Implementation of {$sDeprecatedApi}::{$sDeprecatedMethod}() in class {$sImplementationClass}";
+
+		if (!is_null($sAdditionalMessage)) {
+			$sMessage .= " : $sAdditionalMessage";
+		}
+
+		static::Warning($sMessage, self::ENUM_CHANNEL_PHP_API);
+	}
+
 	/**
 	 * @param string|null $sAdditionalMessage
 	 *

sources/Application/WebPage/iTopWebPage.php

@@ -37,6 +37,8 @@ use DeprecatedCallsLog;
 use Dict;
 use ExecutionKPI;
 use InlineImage;
+use iPageUIBlockExtension;
+use iPageUIExtension;
 use MetaModel;
 use UserRights;
 use utils;
@@ -635,9 +637,10 @@ JS
 		$sBannerHtml = '';
 
 		// Call the extensions to add content to the page, warning they can also add styles or scripts through as they have access to the iTopWebPage
+		$sAPIClassName = iPageUIExtension::class;
 		/** @var \iPageUIExtension $oExtensionInstance */
-		foreach (MetaModel::EnumPlugins('iPageUIExtension') as $oExtensionInstance)
+		foreach (MetaModel::EnumPlugins($sAPIClassName) as $oExtensionInstance) {
-		{
+			DeprecatedCallsLog::NotifyDeprecatedPhpApi(get_class($oExtensionInstance), $sAPIClassName, "GetBannerHtml", "use " . iPageUIBlockExtension::class . "::GetBannerBlock() instead");
 			$sBannerHtml .= $oExtensionInstance->GetBannerHtml($this);
 		}
 
@@ -684,9 +687,10 @@ JS
 		$sHeaderHtml = '';
 
 		// Call the extensions to add content to the page, warning they can also add styles or scripts through as they have access to the iTopWebPage
+		$sAPIClassName = iPageUIExtension::class;
 		/** @var \iPageUIExtension $oExtensionInstance */
-		foreach (MetaModel::EnumPlugins('iPageUIExtension') as $oExtensionInstance)
+		foreach (MetaModel::EnumPlugins($sAPIClassName) as $oExtensionInstance) {
-		{
+			DeprecatedCallsLog::NotifyDeprecatedPhpApi(get_class($oExtensionInstance), $sAPIClassName, "GetNorthPaneHtml", "use " . iPageUIBlockExtension::class . "::GetHeaderBlock() instead");
 			$sHeaderHtml .= $oExtensionInstance->GetNorthPaneHtml($this);
 		}
 
@@ -782,8 +786,10 @@ HTML;
 		$sFooterHtml = '';
 
 		// Call the extensions to add content to the page, warning they can also add styles or scripts through as they have access to the iTopWebPage
+		$sAPIClassName = iPageUIExtension::class;
 		/** @var \iPageUIExtension $oExtensionInstance */
-		foreach (MetaModel::EnumPlugins('iPageUIExtension') as $oExtensionInstance) {
+		foreach (MetaModel::EnumPlugins($sAPIClassName) as $oExtensionInstance) {
+			DeprecatedCallsLog::NotifyDeprecatedPhpApi(get_class($oExtensionInstance), $sAPIClassName, "GetSouthPaneHtml", "use " . iPageUIBlockExtension::class . "::GetFooterBlock() instead");
 			$sFooterHtml .= $oExtensionInstance->GetSouthPaneHtml($this);
 		}