Skip to content

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.md
index 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.md
index 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.php
index 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)) {