A free, self-hostable news aggregator…
New extension methods to get typed configuration values (#8696)
Alexandre Alapetite075101fa66c7
diff --git a/docs/en/developers/03_Backend/05_Extensions.md b/docs/en/developers/03_Backend/05_Extensions.mdindex b333bd62d..0d15f7a2b 100644--- a/docs/en/developers/03_Backend/05_Extensions.md+++ b/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;}diff --git a/docs/fr/developers/03_Backend/05_Extensions.md b/docs/fr/developers/03_Backend/05_Extensions.mdindex 17e6cfca6..715e7bd7b 100644--- a/docs/fr/developers/03_Backend/05_Extensions.md+++ b/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;}diff --git a/lib/Minz/Extension.php b/lib/Minz/Extension.phpindex 8c02caa3f..cda478e66 100644--- a/lib/Minz/Extension.php+++ b/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)) {