New extension methods to get typed configuration values (#8696)

And also correctly scoped in a sub-key per extension, instead of risking collisions between extensions.

docs/en/developers/03_Backend/05_Extensions.md

@@ -123,11 +123,11 @@ The `Minz_Extension` abstract class defines another set of methods that should n
 * the `registerViews` method registers the extension views in FreshRSS.
 * the `registerTranslates` method registers the extension translation files in FreshRSS.
 * the `registerHook` method registers hook actions in different part of the application.
-* the `getSystemConfiguration` method retrieves the extension configuration for the system.
-* the `setSystemConfiguration` method stores the extension configuration for the system.
+* the `getSystemConfiguration*()` family of methods retrieve typed extension configuration values for the system.
+* the `setSystemConfigurationValue()` method stores an extension configuration value for the system.
 * the `removeSystemConfiguration` method removes the extension configuration for the system.
-* the `getUserConfiguration` method retrieves the extension configuration for the current user.
-* the `setUserConfiguration` method stores the extension configuration for the current user.
+* the `getUserConfiguration*()` family of methods retrieve typed extension configuration values for the current user.
+* the `setUserConfigurationValue()` method stores an extension configuration value for the current user.
 * the `removeUserConfiguration` method removes the extension configuration for the current user.
 
 > Note that if you modify the later set of methods, you might break the extension system. Thus making FreshRSS unusable. So it’s highly recommended to let those unmodified.
@@ -151,7 +151,7 @@ final class HelloWorldExtension extends Minz_Extension
 	}
 
 	public function renderEntry(FreshRSS_Entry $entry): FreshRSS_Entry {
-		$message = $this->getUserConfigurationValue('message');
+		$message = $this->getUserConfigurationString('message');
 		$entry->_content("<h1>{$message}</h1>" . $entry->content());
 		return $entry;
 	}

docs/fr/developers/03_Backend/05_Extensions.md

@@ -205,7 +205,7 @@ final class HelloWorldExtension extends Minz_Extension
 	}
 
 	public function renderEntry(FreshRSS_Entry $entry): FreshRSS_Entry {
-		$message = $this->getUserConfigurationValue('message');
+		$message = $this->getUserConfigurationString('message');
 		$entry->_content("<h1>{$message}</h1>" . $entry->content());
 		return $entry;
 	}

lib/Minz/Extension.php

@@ -302,6 +302,8 @@ abstract class Minz_Extension {
 
 	/**
 	 * @return array<string,mixed>
+	 * @deprecated Use typed versions instead. Will soon be marked as private.
+	 * @internal
 	 */
 	final protected function getSystemConfiguration(): array {
 		if ($this->isConfigurationEnabled('system') && $this->isExtensionConfigured('system')) {
@@ -312,6 +314,8 @@ abstract class Minz_Extension {
 
 	/**
 	 * @return array<string,mixed>
+	 * @deprecated Use typed versions instead. Will soon be marked as private.
+	 * @internal
 	 */
 	final protected function getUserConfiguration(): array {
 		if ($this->isConfigurationEnabled('user') && $this->isExtensionConfigured('user')) {
@@ -320,6 +324,10 @@ abstract class Minz_Extension {
 		return [];
 	}
 
+	/**
+	 * @deprecated Use typed versions instead. Will soon be marked as private.
+	 * @internal
+	 */
 	final public function getSystemConfigurationValue(string $key, mixed $default = null): mixed {
 		if (!is_array($this->system_configuration)) {
 			$this->system_configuration = $this->getSystemConfiguration();
@@ -331,6 +339,41 @@ abstract class Minz_Extension {
 		return $default;
 	}
 
+	/**
+	 * @param non-empty-string $key
+	 * @return array<int|string,mixed>|null
+	 */
+	final public function getSystemConfigurationArray(string $key): ?array {
+		/** @phpstan-ignore method.deprecated */
+		$a = $this->getSystemConfigurationValue($key);
+		return is_array($a) ? $a : null;
+	}
+
+	/** @param non-empty-string $key */
+	final public function getSystemConfigurationBool(string $key): ?bool {
+		/** @phpstan-ignore method.deprecated */
+		$a = $this->getSystemConfigurationValue($key);
+		return is_bool($a) ? $a : null;
+	}
+
+	/** @param non-empty-string $key */
+	final public function getSystemConfigurationInt(string $key): ?int {
+		/** @phpstan-ignore method.deprecated */
+		$a = $this->getSystemConfigurationValue($key);
+		return is_numeric($a) ? (int)$a : null;
+	}
+
+	/** @param non-empty-string $key */
+	final public function getSystemConfigurationString(string $key): ?string {
+		/** @phpstan-ignore method.deprecated */
+		$a = $this->getSystemConfigurationValue($key);
+		return is_string($a) ? $a : null;
+	}
+
+	/**
+	 * @deprecated Use typed versions instead. Will soon be marked as private.
+	 * @internal
+	 */
 	final public function getUserConfigurationValue(string $key, mixed $default = null): mixed {
 		if (!is_array($this->user_configuration)) {
 			$this->user_configuration = $this->getUserConfiguration();
@@ -342,6 +385,37 @@ abstract class Minz_Extension {
 		return $default;
 	}
 
+	/**
+	 * @param non-empty-string $key
+	 * @return array<int|string,mixed>|null
+	 */
+	final public function getUserConfigurationArray(string $key): ?array {
+		// @phpstan-ignore-next-line method.deprecated
+		$a = $this->getUserConfigurationValue($key);
+		return is_array($a) ? $a : null;
+	}
+
+	/** @param non-empty-string $key */
+	final public function getUserConfigurationBool(string $key): ?bool {
+		// @phpstan-ignore-next-line method.deprecated
+		$a = $this->getUserConfigurationValue($key);
+		return is_bool($a) ? $a : null;
+	}
+
+	/** @param non-empty-string $key */
+	final public function getUserConfigurationInt(string $key): ?int {
+		// @phpstan-ignore-next-line method.deprecated
+		$a = $this->getUserConfigurationValue($key);
+		return is_numeric($a) ? (int)$a : null;
+	}
+
+	/** @param non-empty-string $key */
+	final public function getUserConfigurationString(string $key): ?string {
+		// @phpstan-ignore-next-line method.deprecated
+		$a = $this->getUserConfigurationValue($key);
+		return is_string($a) ? $a : null;
+	}
+
 	/**
 	 * @param 'system'|'user' $type
 	 * @param array<string,mixed> $configuration
@@ -369,18 +443,64 @@ abstract class Minz_Extension {
 		$conf->save();
 	}
 
-	/** @param array<string,mixed> $configuration */
+	/**
+	 * @param array<string,mixed> $configuration
+	 * @deprecated Use {@see setSystemConfigurationValue()} instead. Will soon be marked as private.
+	 * @internal
+	 */
 	final protected function setSystemConfiguration(array $configuration): void {
 		$this->setConfiguration('system', $configuration);
 		$this->system_configuration = $configuration;
 	}
 
-	/** @param array<string,mixed> $configuration */
+	/**
+	 * @param non-empty-string $key
+	 * @param array<string,mixed>|mixed|null $value
+	 */
+	final protected function setSystemConfigurationValue(string $key, $value = null): void {
+		if (!is_array($this->system_configuration)) {
+			/** @phpstan-ignore method.deprecated */
+			$this->system_configuration = $this->getSystemConfiguration();
+		}
+
+		if (isset($this->system_configuration[$key]) && $value === null) {
+			unset($this->system_configuration[$key]);
+		} elseif ($value !== null) {
+			$this->system_configuration[$key] = $value;
+		}
+
+		$this->setConfiguration('system', $this->system_configuration);
+	}
+
+	/**
+	 * @param array<string,mixed> $configuration
+	 * @deprecated Use {@see setUserConfigurationValue()} instead. Will soon be marked as private.
+	 * @internal
+	 */
 	final protected function setUserConfiguration(array $configuration): void {
 		$this->setConfiguration('user', $configuration);
 		$this->user_configuration = $configuration;
 	}
 
+	/**
+	 * @param non-empty-string $key
+	 * @param array<string,mixed>|mixed|null $value
+	 */
+	final protected function setUserConfigurationValue(string $key, $value = null): void {
+		if (!is_array($this->user_configuration)) {
+			/** @phpstan-ignore method.deprecated */
+			$this->user_configuration = $this->getUserConfiguration();
+		}
+
+		if (isset($this->user_configuration[$key]) && $value === null) {
+			unset($this->user_configuration[$key]);
+		} elseif ($value !== null) {
+			$this->user_configuration[$key] = $value;
+		}
+
+		$this->setConfiguration('user', $this->user_configuration);
+	}
+
 	/** @phpstan-param 'system'|'user' $type */
 	private function removeConfiguration(string $type): void {
 		if (!$this->isConfigurationEnabled($type) || !$this->isExtensionConfigured($type)) {