aboutsummaryrefslogtreecommitdiffstats
path: root/lib/public
diff options
context:
space:
mode:
Diffstat (limited to 'lib/public')
-rw-r--r--lib/public/AppFramework/Bootstrap/IRegistrationContext.php2
-rw-r--r--lib/public/Config/BeforePreferenceDeletedEvent.php5
-rw-r--r--lib/public/Config/BeforePreferenceSetEvent.php5
-rw-r--r--lib/public/Config/Exceptions/IncorrectTypeException.php16
-rw-r--r--lib/public/Config/Exceptions/TypeConflictException.php16
-rw-r--r--lib/public/Config/Exceptions/UnknownKeyException.php16
-rw-r--r--lib/public/Config/IUserConfig.php742
-rw-r--r--lib/public/Config/Lexicon/Entry.php250
-rw-r--r--lib/public/Config/Lexicon/ILexicon.php45
-rw-r--r--lib/public/Config/Lexicon/Preset.php50
-rw-r--r--lib/public/Config/Lexicon/Strictness.php31
-rw-r--r--lib/public/Config/ValueType.php117
-rw-r--r--lib/public/Federation/ICloudIdManager.php27
-rw-r--r--lib/public/Federation/ICloudIdResolver.php40
14 files changed, 1355 insertions, 7 deletions
diff --git a/lib/public/AppFramework/Bootstrap/IRegistrationContext.php b/lib/public/AppFramework/Bootstrap/IRegistrationContext.php
index 011d1520414..70b35228c87 100644
--- a/lib/public/AppFramework/Bootstrap/IRegistrationContext.php
+++ b/lib/public/AppFramework/Bootstrap/IRegistrationContext.php
@@ -443,7 +443,7 @@ interface IRegistrationContext {
*
* @param string $configLexiconClass
*
- * @psalm-param class-string<\NCU\Config\Lexicon\IConfigLexicon> $configLexiconClass
+ * @psalm-param class-string<\OCP\Config\Lexicon\ILexicon> $configLexiconClass
* @since 31.0.0
*/
public function registerConfigLexicon(string $configLexiconClass): void;
diff --git a/lib/public/Config/BeforePreferenceDeletedEvent.php b/lib/public/Config/BeforePreferenceDeletedEvent.php
index c7026b0f6fc..df89a2900bd 100644
--- a/lib/public/Config/BeforePreferenceDeletedEvent.php
+++ b/lib/public/Config/BeforePreferenceDeletedEvent.php
@@ -8,11 +8,10 @@ declare(strict_types=1);
namespace OCP\Config;
+use OCP\AppFramework\Attribute\Listenable;
use OCP\EventDispatcher\Event;
-/**
- * @since 25.0.0
- */
+#[Listenable(since: '25.0.0')]
class BeforePreferenceDeletedEvent extends Event {
protected string $userId;
protected string $appId;
diff --git a/lib/public/Config/BeforePreferenceSetEvent.php b/lib/public/Config/BeforePreferenceSetEvent.php
index c5abb8429a8..6534e4ae371 100644
--- a/lib/public/Config/BeforePreferenceSetEvent.php
+++ b/lib/public/Config/BeforePreferenceSetEvent.php
@@ -8,11 +8,10 @@ declare(strict_types=1);
namespace OCP\Config;
+use OCP\AppFramework\Attribute\Listenable;
use OCP\EventDispatcher\Event;
-/**
- * @since 25.0.0
- */
+#[Listenable(since: '25.0.0')]
class BeforePreferenceSetEvent extends Event {
protected string $userId;
protected string $appId;
diff --git a/lib/public/Config/Exceptions/IncorrectTypeException.php b/lib/public/Config/Exceptions/IncorrectTypeException.php
new file mode 100644
index 00000000000..dea33233bfe
--- /dev/null
+++ b/lib/public/Config/Exceptions/IncorrectTypeException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Config\Exceptions;
+
+use Exception;
+use OCP\AppFramework\Attribute\Throwable;
+
+#[Throwable(since: '32.0.0')]
+class IncorrectTypeException extends Exception {
+}
diff --git a/lib/public/Config/Exceptions/TypeConflictException.php b/lib/public/Config/Exceptions/TypeConflictException.php
new file mode 100644
index 00000000000..c78602180e0
--- /dev/null
+++ b/lib/public/Config/Exceptions/TypeConflictException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Config\Exceptions;
+
+use Exception;
+use OCP\AppFramework\Attribute\Throwable;
+
+#[Throwable(since: '32.0.0')]
+class TypeConflictException extends Exception {
+}
diff --git a/lib/public/Config/Exceptions/UnknownKeyException.php b/lib/public/Config/Exceptions/UnknownKeyException.php
new file mode 100644
index 00000000000..beca4c496a2
--- /dev/null
+++ b/lib/public/Config/Exceptions/UnknownKeyException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Config\Exceptions;
+
+use Exception;
+use OCP\AppFramework\Attribute\Throwable;
+
+#[Throwable(since: '32.0.0')]
+class UnknownKeyException extends Exception {
+}
diff --git a/lib/public/Config/IUserConfig.php b/lib/public/Config/IUserConfig.php
new file mode 100644
index 00000000000..cb42608ea75
--- /dev/null
+++ b/lib/public/Config/IUserConfig.php
@@ -0,0 +1,742 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Config;
+
+use Generator;
+use OCP\AppFramework\Attribute\Consumable;
+use OCP\Config\Exceptions\IncorrectTypeException;
+use OCP\Config\Exceptions\UnknownKeyException;
+
+/**
+ * This class provides an easy way for apps to store user config in the
+ * database.
+ * Supports **lazy loading**
+ *
+ * ### What is lazy loading ?
+ * In order to avoid loading useless user config into memory for each request,
+ * only non-lazy values are now loaded.
+ *
+ * Once a value that is lazy is requested, all lazy values will be loaded.
+ *
+ * Similarly, some methods from this class are marked with a warning about ignoring
+ * lazy loading. Use them wisely and only on parts of the code that are called
+ * during specific requests or actions to avoid loading the lazy values all the time.
+ */
+#[Consumable(since: '32.0.0')]
+interface IUserConfig {
+ /**
+ * @since 32.0.0
+ */
+ public const FLAG_SENSITIVE = 1; // value is sensitive
+ /**
+ * @since 32.0.0
+ */
+ public const FLAG_INDEXED = 2; // value should be indexed
+
+ /**
+ * Get list of all userIds with config stored in database.
+ * If $appId is specified, will only limit the search to this value
+ *
+ * **WARNING:** ignore any cache and get data directly from database.
+ *
+ * @param string $appId optional id of app
+ *
+ * @return list<string> list of userIds
+ *
+ * @since 32.0.0
+ */
+ public function getUserIds(string $appId = ''): array;
+
+ /**
+ * Get list of all apps that have at least one config
+ * value related to $userId stored in database
+ *
+ * **WARNING:** ignore lazy filtering, all user config are loaded from database
+ *
+ * @param string $userId id of the user
+ *
+ * @return list<string> list of app ids
+ *
+ * @since 32.0.0
+ */
+ public function getApps(string $userId): array;
+
+ /**
+ * Returns all keys stored in database, related to user+app.
+ * Please note that the values are not returned.
+ *
+ * **WARNING:** ignore lazy filtering, all user config are loaded from database
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ *
+ * @return list<string> list of stored config keys
+ *
+ * @since 32.0.0
+ */
+ public function getKeys(string $userId, string $app): array;
+
+ /**
+ * Check if a key exists in the list of stored config values.
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $lazy search within lazy loaded config
+ *
+ * @return bool TRUE if key exists
+ *
+ * @since 32.0.0
+ */
+ public function hasKey(string $userId, string $app, string $key, ?bool $lazy = false): bool;
+
+ /**
+ * best way to see if a value is set as sensitive (not displayed in report)
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool|null $lazy search within lazy loaded config
+ *
+ * @return bool TRUE if value is sensitive
+ * @throws UnknownKeyException if config key is not known
+ *
+ * @since 32.0.0
+ */
+ public function isSensitive(string $userId, string $app, string $key, ?bool $lazy = false): bool;
+
+ /**
+ * best way to see if a value is set as indexed (so it can be search)
+ *
+ * @see self::searchUsersByValueString()
+ * @see self::searchUsersByValueInt()
+ * @see self::searchUsersByValueBool()
+ * @see self::searchUsersByValues()
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool|null $lazy search within lazy loaded config
+ *
+ * @return bool TRUE if value is sensitive
+ * @throws UnknownKeyException if config key is not known
+ *
+ * @since 32.0.0
+ */
+ public function isIndexed(string $userId, string $app, string $key, ?bool $lazy = false): bool;
+
+ /**
+ * Returns if the config key stored in database is lazy loaded
+ *
+ * **WARNING:** ignore lazy filtering, all config values are loaded from database
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ *
+ * @return bool TRUE if config is lazy loaded
+ * @throws UnknownKeyException if config key is not known
+ * @see IUserConfig for details about lazy loading
+ *
+ * @since 32.0.0
+ */
+ public function isLazy(string $userId, string $app, string $key): bool;
+
+ /**
+ * List all config values from an app with config key starting with $key.
+ * Returns an array with config key as key, stored value as value.
+ *
+ * **WARNING:** ignore lazy filtering, all config values are loaded from database
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $prefix config keys prefix to search, can be empty.
+ * @param bool $filtered filter sensitive config values
+ *
+ * @return array<string, string|int|float|bool|array> [key => value]
+ *
+ * @since 32.0.0
+ */
+ public function getValues(string $userId, string $app, string $prefix = '', bool $filtered = false): array;
+
+ /**
+ * List all config values of a user.
+ * Returns an array with config key as key, stored value as value.
+ *
+ * **WARNING:** ignore lazy filtering, all config values are loaded from database
+ *
+ * @param string $userId id of the user
+ * @param bool $filtered filter sensitive config values
+ *
+ * @return array<string, string|int|float|bool|array> [key => value]
+ *
+ * @since 32.0.0
+ */
+ public function getAllValues(string $userId, bool $filtered = false): array;
+
+ /**
+ * List all apps storing a specific config key and its stored value.
+ * Returns an array with appId as key, stored value as value.
+ *
+ * @param string $userId id of the user
+ * @param string $key config key
+ * @param bool $lazy search within lazy loaded config
+ * @param ValueType|null $typedAs enforce type for the returned values
+ *
+ * @return array<string, string|int|float|bool|array> [appId => value]
+ *
+ * @since 32.0.0
+ */
+ public function getValuesByApps(string $userId, string $key, bool $lazy = false, ?ValueType $typedAs = null): array;
+
+ /**
+ * List all users storing a specific config key and its stored value.
+ * Returns an array with userId as key, stored value as value.
+ *
+ * **WARNING:** no caching, generate a fresh request
+ *
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param ValueType|null $typedAs enforce type for the returned values
+ * @param array|null $userIds limit the search to a list of user ids
+ *
+ * @return array<string, string|int|float|bool|array> [userId => value]
+ *
+ * @since 32.0.0
+ */
+ public function getValuesByUsers(string $app, string $key, ?ValueType $typedAs = null, ?array $userIds = null): array;
+
+ /**
+ * List all users storing a specific config key/value pair.
+ * Returns a list of user ids.
+ *
+ * **WARNING:** no caching, generate a fresh request
+ *
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param string $value config value
+ * @param bool $caseInsensitive non-case-sensitive search, only works if $value is a string
+ *
+ * @return Generator<string>
+ *
+ * @since 32.0.0
+ */
+ public function searchUsersByValueString(string $app, string $key, string $value, bool $caseInsensitive = false): Generator;
+
+ /**
+ * List all users storing a specific config key/value pair.
+ * Returns a list of user ids.
+ *
+ * **WARNING:** no caching, generate a fresh request
+ *
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param int $value config value
+ *
+ * @return Generator<string>
+ *
+ * @since 32.0.0
+ */
+ public function searchUsersByValueInt(string $app, string $key, int $value): Generator;
+
+ /**
+ * List all users storing a specific config key/value pair.
+ * Returns a list of user ids.
+ *
+ * **WARNING:** no caching, generate a fresh request
+ *
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param array $values list of possible config values
+ *
+ * @return Generator<string>
+ *
+ * @since 32.0.0
+ */
+ public function searchUsersByValues(string $app, string $key, array $values): Generator;
+
+ /**
+ * List all users storing a specific config key/value pair.
+ * Returns a list of user ids.
+ *
+ * **WARNING:** no caching, generate a fresh request
+ *
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $value config value
+ *
+ * @return Generator<string>
+ *
+ * @since 32.0.0
+ */
+ public function searchUsersByValueBool(string $app, string $key, bool $value): Generator;
+
+ /**
+ * Get user config assigned to a config key.
+ * If config key is not found in database, default value is returned.
+ * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param string $default default value
+ * @param bool $lazy search within lazy loaded config
+ *
+ * @return string stored config value or $default if not set in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserConfig for explanation about lazy loading
+ * @see getValueInt()
+ * @see getValueFloat()
+ * @see getValueBool()
+ * @see getValueArray()
+ */
+ public function getValueString(string $userId, string $app, string $key, string $default = '', bool $lazy = false): string;
+
+ /**
+ * Get config value assigned to a config key.
+ * If config key is not found in database, default value is returned.
+ * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param int $default default value
+ * @param bool $lazy search within lazy loaded config
+ *
+ * @return int stored config value or $default if not set in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserConfig for explanation about lazy loading
+ * @see getValueString()
+ * @see getValueFloat()
+ * @see getValueBool()
+ * @see getValueArray()
+ */
+ public function getValueInt(string $userId, string $app, string $key, int $default = 0, bool $lazy = false): int;
+
+ /**
+ * Get config value assigned to a config key.
+ * If config key is not found in database, default value is returned.
+ * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param float $default default value
+ * @param bool $lazy search within lazy loaded config
+ *
+ * @return float stored config value or $default if not set in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserConfig for explanation about lazy loading
+ * @see getValueString()
+ * @see getValueInt()
+ * @see getValueBool()
+ * @see getValueArray()
+ */
+ public function getValueFloat(string $userId, string $app, string $key, float $default = 0, bool $lazy = false): float;
+
+ /**
+ * Get config value assigned to a config key.
+ * If config key is not found in database, default value is returned.
+ * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $default default value
+ * @param bool $lazy search within lazy loaded config
+ *
+ * @return bool stored config value or $default if not set in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserPrefences for explanation about lazy loading
+ * @see getValueString()
+ * @see getValueInt()
+ * @see getValueFloat()
+ * @see getValueArray()
+ */
+ public function getValueBool(string $userId, string $app, string $key, bool $default = false, bool $lazy = false): bool;
+
+ /**
+ * Get config value assigned to a config key.
+ * If config key is not found in database, default value is returned.
+ * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param array $default default value`
+ * @param bool $lazy search within lazy loaded config
+ *
+ * @return array stored config value or $default if not set in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserConfig for explanation about lazy loading
+ * @see getValueString()
+ * @see getValueInt()
+ * @see getValueFloat()
+ * @see getValueBool()
+ */
+ public function getValueArray(string $userId, string $app, string $key, array $default = [], bool $lazy = false): array;
+
+ /**
+ * returns the type of config value
+ *
+ * **WARNING:** ignore lazy filtering, all config values are loaded from database
+ * unless lazy is set to false
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool|null $lazy
+ *
+ * @return ValueType type of the value
+ * @throws UnknownKeyException if config key is not known
+ * @throws IncorrectTypeException if config value type is not known
+ *
+ * @since 32.0.0
+ */
+ public function getValueType(string $userId, string $app, string $key, ?bool $lazy = null): ValueType;
+
+ /**
+ * returns a bitflag related to config value
+ *
+ * **WARNING:** ignore lazy filtering, all config values are loaded from database
+ * unless lazy is set to false
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $lazy lazy loading
+ *
+ * @return int a bitflag in relation to the config value
+ * @throws UnknownKeyException if config key is not known
+ * @throws IncorrectTypeException if config value type is not known
+ *
+ * @since 32.0.0
+ */
+ public function getValueFlags(string $userId, string $app, string $key, bool $lazy = false): int;
+
+ /**
+ * Store a config key and its value in database
+ *
+ * If config key is already known with the exact same config value, the database is not updated.
+ * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
+ *
+ * If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param string $value config value
+ * @param bool $sensitive if TRUE value will be hidden when listing config values.
+ * @param bool $lazy set config as lazy loaded
+ *
+ * @return bool TRUE if value was different, therefor updated in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserConfig for explanation about lazy loading
+ * @see setValueInt()
+ * @see setValueFloat()
+ * @see setValueBool()
+ * @see setValueArray()
+ */
+ public function setValueString(string $userId, string $app, string $key, string $value, bool $lazy = false, int $flags = 0): bool;
+
+ /**
+ * Store a config key and its value in database
+ *
+ * When handling huge value around and/or above 2,147,483,647, a debug log will be generated
+ * on 64bits system, as php int type reach its limit (and throw an exception) on 32bits when using huge numbers.
+ *
+ * When using huge numbers, it is advised to use {@see \OCP\Util::numericToNumber()} and {@see setValueString()}
+ *
+ * If config key is already known with the exact same config value, the database is not updated.
+ * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
+ *
+ * If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param int $value config value
+ * @param bool $sensitive if TRUE value will be hidden when listing config values.
+ * @param bool $lazy set config as lazy loaded
+ *
+ * @return bool TRUE if value was different, therefor updated in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserConfig for explanation about lazy loading
+ * @see setValueString()
+ * @see setValueFloat()
+ * @see setValueBool()
+ * @see setValueArray()
+ */
+ public function setValueInt(string $userId, string $app, string $key, int $value, bool $lazy = false, int $flags = 0): bool;
+
+ /**
+ * Store a config key and its value in database.
+ *
+ * If config key is already known with the exact same config value, the database is not updated.
+ * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
+ *
+ * If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param float $value config value
+ * @param bool $sensitive if TRUE value will be hidden when listing config values.
+ * @param bool $lazy set config as lazy loaded
+ *
+ * @return bool TRUE if value was different, therefor updated in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserConfig for explanation about lazy loading
+ * @see setValueString()
+ * @see setValueInt()
+ * @see setValueBool()
+ * @see setValueArray()
+ */
+ public function setValueFloat(string $userId, string $app, string $key, float $value, bool $lazy = false, int $flags = 0): bool;
+
+ /**
+ * Store a config key and its value in database
+ *
+ * If config key is already known with the exact same config value, the database is not updated.
+ * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
+ *
+ * If config value was previously stored as lazy loaded, status cannot be altered without using {@see deleteKey()} first
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $value config value
+ * @param bool $lazy set config as lazy loaded
+ *
+ * @return bool TRUE if value was different, therefor updated in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserConfig for explanation about lazy loading
+ * @see setValueString()
+ * @see setValueInt()
+ * @see setValueFloat()
+ * @see setValueArray()
+ */
+ public function setValueBool(string $userId, string $app, string $key, bool $value, bool $lazy = false): bool;
+
+ /**
+ * Store a config key and its value in database
+ *
+ * If config key is already known with the exact same config value, the database is not updated.
+ * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
+ *
+ * If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param array $value config value
+ * @param bool $sensitive if TRUE value will be hidden when listing config values.
+ * @param bool $lazy set config as lazy loaded
+ *
+ * @return bool TRUE if value was different, therefor updated in database
+ *
+ * @since 32.0.0
+ *
+ * @see IUserConfig for explanation about lazy loading
+ * @see setValueString()
+ * @see setValueInt()
+ * @see setValueFloat()
+ * @see setValueBool()
+ */
+ public function setValueArray(string $userId, string $app, string $key, array $value, bool $lazy = false, int $flags = 0): bool;
+
+ /**
+ * switch sensitive status of a config value
+ *
+ * **WARNING:** ignore lazy filtering, all config values are loaded from database
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $sensitive TRUE to set as sensitive, FALSE to unset
+ *
+ * @return bool TRUE if database update were necessary
+ *
+ * @since 32.0.0
+ */
+ public function updateSensitive(string $userId, string $app, string $key, bool $sensitive): bool;
+
+ /**
+ * switch sensitive loading status of a config key for all users
+ *
+ * **Warning:** heavy on resources, MUST only be used on occ command or migrations
+ *
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $sensitive TRUE to set as sensitive, FALSE to unset
+ *
+ * @since 32.0.0
+ */
+ public function updateGlobalSensitive(string $app, string $key, bool $sensitive): void;
+
+
+ /**
+ * switch indexed status of a config value
+ *
+ * **WARNING:** ignore lazy filtering, all config values are loaded from database
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $indexed TRUE to set as indexed, FALSE to unset
+ *
+ * @return bool TRUE if database update were necessary
+ *
+ * @since 32.0.0
+ */
+ public function updateIndexed(string $userId, string $app, string $key, bool $indexed): bool;
+
+ /**
+ * switch sensitive loading status of a config key for all users
+ *
+ * **Warning:** heavy on resources, MUST only be used on occ command or migrations
+ *
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $indexed TRUE to set as indexed, FALSE to unset
+ *
+ * @since 32.0.0
+ */
+ public function updateGlobalIndexed(string $app, string $key, bool $indexed): void;
+
+ /**
+ * switch lazy loading status of a config value
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $lazy TRUE to set as lazy loaded, FALSE to unset
+ *
+ * @return bool TRUE if database update was necessary
+ *
+ * @since 32.0.0
+ */
+ public function updateLazy(string $userId, string $app, string $key, bool $lazy): bool;
+
+ /**
+ * switch lazy loading status of a config key for all users
+ *
+ * **Warning:** heavy on resources, MUST only be used on occ command or migrations
+ *
+ * @param string $app id of the app
+ * @param string $key config key
+ * @param bool $lazy TRUE to set as lazy loaded, FALSE to unset
+ *
+ * @since 32.0.0
+ */
+ public function updateGlobalLazy(string $app, string $key, bool $lazy): void;
+
+ /**
+ * returns an array contains details about a config value
+ *
+ * ```
+ * [
+ * "app" => "myapp",
+ * "key" => "mykey",
+ * "value" => "its_value",
+ * "lazy" => false,
+ * "type" => 4,
+ * "typeString" => "string",
+ * 'sensitive' => true
+ * ]
+ * ```
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ *
+ * @return array
+ * @throws UnknownKeyException if config key is not known in database
+ *
+ * @since 32.0.0
+ */
+ public function getDetails(string $userId, string $app, string $key): array;
+
+ /**
+ * Delete single config key from database.
+ *
+ * @param string $userId id of the user
+ * @param string $app id of the app
+ * @param string $key config key
+ *
+ * @since 32.0.0
+ */
+ public function deleteUserConfig(string $userId, string $app, string $key): void;
+
+ /**
+ * Delete config values from all users linked to a specific config keys
+ *
+ * @param string $app id of the app
+ * @param string $key config key
+ *
+ * @since 32.0.0
+ */
+ public function deleteKey(string $app, string $key): void;
+
+ /**
+ * delete all config keys linked to an app
+ *
+ * @param string $app id of the app
+ *
+ * @since 32.0.0
+ */
+ public function deleteApp(string $app): void;
+
+ /**
+ * delete all config keys linked to a user
+ *
+ * @param string $userId id of the user
+ *
+ * @since 32.0.0
+ */
+ public function deleteAllUserConfig(string $userId): void;
+
+ /**
+ * Clear the cache for a single user
+ *
+ * The cache will be rebuilt only the next time a user config is requested.
+ *
+ * @param string $userId id of the user
+ * @param bool $reload set to TRUE to refill cache instantly after clearing it
+ *
+ * @since 32.0.0
+ */
+ public function clearCache(string $userId, bool $reload = false): void;
+
+ /**
+ * Clear the cache for all users.
+ * The cache will be rebuilt only the next time a user config is requested.
+ *
+ * @since 32.0.0
+ */
+ public function clearCacheAll(): void;
+}
diff --git a/lib/public/Config/Lexicon/Entry.php b/lib/public/Config/Lexicon/Entry.php
new file mode 100644
index 00000000000..0e6e664db36
--- /dev/null
+++ b/lib/public/Config/Lexicon/Entry.php
@@ -0,0 +1,250 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Config\Lexicon;
+
+use Closure;
+use OCP\AppFramework\Attribute\Consumable;
+use OCP\Config\ValueType;
+
+/**
+ * Model that represent config values within an app config lexicon.
+ *
+ * @see ILexicon
+ */
+#[Consumable(since: '32.0.0')]
+class Entry {
+ /** @since 32.0.0 */
+ public const RENAME_INVERT_BOOLEAN = 1;
+
+ private string $definition = '';
+ private ?string $default = null;
+
+ /**
+ * @param string $key config key, can only contain alphanumerical chars and -._
+ * @param ValueType $type type of config value
+ * @param string $definition optional description of config key available when using occ command
+ * @param bool $lazy set config value as lazy
+ * @param int $flags set flags
+ * @param string|null $rename previous config key to migrate config value from
+ * @param bool $deprecated set config key as deprecated
+ *
+ * @since 32.0.0
+ * @psalm-suppress PossiblyInvalidCast
+ * @psalm-suppress RiskyCast
+ */
+ public function __construct(
+ private readonly string $key,
+ private readonly ValueType $type,
+ private null|string|int|float|bool|array|Closure $defaultRaw = null,
+ string $definition = '',
+ private readonly bool $lazy = false,
+ private readonly int $flags = 0,
+ private readonly bool $deprecated = false,
+ private readonly ?string $rename = null,
+ private readonly int $options = 0,
+ ) {
+ // key can only contain alphanumeric chars and underscore "_"
+ if (preg_match('/[^[:alnum:]_]/', $key)) {
+ throw new \Exception('invalid config key');
+ }
+
+ /** @psalm-suppress UndefinedClass */
+ if (\OC::$CLI) { // only store definition if ran from CLI
+ $this->definition = $definition;
+ }
+ }
+
+ /**
+ * returns the config key
+ *
+ * @return string config key
+ * @since 32.0.0
+ */
+ public function getKey(): string {
+ return $this->key;
+ }
+
+ /**
+ * get expected type for config value
+ *
+ * @return ValueType
+ * @since 32.0.0
+ */
+ public function getValueType(): ValueType {
+ return $this->type;
+ }
+
+ /**
+ * @param string $default
+ * @return string
+ * @since 32.0.0
+ */
+ private function convertFromString(string $default): string {
+ return $default;
+ }
+
+ /**
+ * @param int $default
+ * @return string
+ * @since 32.0.0
+ */
+ private function convertFromInt(int $default): string {
+ return (string)$default;
+ }
+
+ /**
+ * @param float $default
+ * @return string
+ * @since 32.0.0
+ */
+ private function convertFromFloat(float $default): string {
+ return (string)$default;
+ }
+
+ /**
+ * @param bool $default
+ * @return string
+ * @since 32.0.0
+ */
+ private function convertFromBool(bool $default): string {
+ return ($default) ? '1' : '0';
+ }
+
+ /**
+ * @param array $default
+ * @return string
+ * @since 32.0.0
+ */
+ private function convertFromArray(array $default): string {
+ return json_encode($default);
+ }
+
+ /**
+ * returns default value
+ *
+ * @return string|null NULL if no default is set
+ * @since 32.0.0
+ */
+ public function getDefault(Preset $preset): ?string {
+ if ($this->default !== null) {
+ return $this->default;
+ }
+
+ if ($this->defaultRaw === null) {
+ return null;
+ }
+
+ if ($this->defaultRaw instanceof Closure) {
+ /** @psalm-suppress MixedAssignment we expect closure to returns string|int|float|bool|array */
+ $this->defaultRaw = ($this->defaultRaw)($preset);
+ }
+
+ /** @psalm-suppress MixedArgument closure should be managed previously */
+ $this->default = $this->convertToString($this->defaultRaw);
+
+ return $this->default;
+ }
+
+ /**
+ * convert $entry into string, based on the expected type for config value
+ *
+ * @param string|int|float|bool|array $entry
+ *
+ * @return string
+ * @since 32.0.0
+ * @psalm-suppress PossiblyInvalidCast arrays are managed pre-cast
+ * @psalm-suppress RiskyCast
+ */
+ public function convertToString(string|int|float|bool|array $entry): string {
+ // in case $default is array but is not expected to be an array...
+ if ($this->getValueType() !== ValueType::ARRAY && is_array($entry)) {
+ $entry = json_encode($entry, JSON_THROW_ON_ERROR);
+ }
+
+ return match ($this->getValueType()) {
+ ValueType::MIXED => (string)$entry,
+ ValueType::STRING => $this->convertFromString((string)$entry),
+ ValueType::INT => $this->convertFromInt((int)$entry),
+ ValueType::FLOAT => $this->convertFromFloat((float)$entry),
+ ValueType::BOOL => $this->convertFromBool((bool)$entry),
+ ValueType::ARRAY => $this->convertFromArray((array)$entry)
+ };
+ }
+
+ /**
+ * returns definition
+ *
+ * @return string
+ * @since 32.0.0
+ */
+ public function getDefinition(): string {
+ return $this->definition;
+ }
+
+ /**
+ * returns if config key is set as lazy
+ *
+ * @see IAppConfig for details on lazy config values
+ * @return bool TRUE if config value is lazy
+ * @since 32.0.0
+ */
+ public function isLazy(): bool {
+ return $this->lazy;
+ }
+
+ /**
+ * returns flags
+ *
+ * @see IAppConfig for details on sensitive config values
+ * @return int bitflag about the config value
+ * @since 32.0.0
+ */
+ public function getFlags(): int {
+ return $this->flags;
+ }
+
+ /**
+ * @param int $flag
+ *
+ * @return bool TRUE is config value bitflag contains $flag
+ * @since 32.0.0
+ */
+ public function isFlagged(int $flag): bool {
+ return (($flag & $this->getFlags()) === $flag);
+ }
+
+ /**
+ * should be called/used only during migration/upgrade.
+ * link to an old config key.
+ *
+ * @return string|null not NULL if value can be imported from a previous key
+ * @since 32.0.0
+ */
+ public function getRename(): ?string {
+ return $this->rename;
+ }
+
+ /**
+ * @since 32.0.0
+ * @return bool TRUE if $option was set during the creation of the entry.
+ */
+ public function hasOption(int $option): bool {
+ return (($option & $this->options) !== 0);
+ }
+
+ /**
+ * returns if config key is set as deprecated
+ *
+ * @return bool TRUE if config si deprecated
+ * @since 32.0.0
+ */
+ public function isDeprecated(): bool {
+ return $this->deprecated;
+ }
+}
diff --git a/lib/public/Config/Lexicon/ILexicon.php b/lib/public/Config/Lexicon/ILexicon.php
new file mode 100644
index 00000000000..05bf5967f24
--- /dev/null
+++ b/lib/public/Config/Lexicon/ILexicon.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP\Config\Lexicon;
+
+use OCP\AppFramework\Attribute\Implementable;
+
+/**
+ * This interface needs to be implemented if you want to define a config lexicon for your application
+ * The config lexicon is used to avoid conflicts and problems when storing/retrieving config values
+ */
+#[Implementable(since: '32.0.0')]
+interface ILexicon {
+
+ /**
+ * Define the expected behavior when using config
+ * keys not set within your application config lexicon.
+ *
+ * @return Strictness
+ * @since 32.0.0
+ *@see Strictness
+ */
+ public function getStrictness(): Strictness;
+
+ /**
+ * define the list of entries of your application config lexicon, related to AppConfig.
+ *
+ * @return Entry[]
+ * @since 32.0.0
+ */
+ public function getAppConfigs(): array;
+
+ /**
+ * define the list of entries of your application config lexicon, related to UserPreferences.
+ *
+ * @return Entry[]
+ * @since 32.0.0
+ */
+ public function getUserConfigs(): array;
+}
diff --git a/lib/public/Config/Lexicon/Preset.php b/lib/public/Config/Lexicon/Preset.php
new file mode 100644
index 00000000000..6dac8736131
--- /dev/null
+++ b/lib/public/Config/Lexicon/Preset.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP\Config\Lexicon;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+/**
+ * list of preset to handle the default behavior of the instance
+ *
+ * @see Entry::preset
+ *
+ * - **Preset::LARGE** - Large size organisation (> 50k accounts)
+ * - **Preset::MEDIUM** - Medium size organisation (> 100 accounts)
+ * - **Preset::SMALL** - Small size organisation (< 100 accounts)
+ * - **Preset::SHARED** - Shared hosting
+ * - **Preset::UNIVERSITY** - Education, large size
+ * - **Preset::SCHOOL** - Eduction, small/medium size
+ * - **Preset::CLUB** - Club/Association
+ * - **Preset::FAMILY** - Family
+ * - **Preset::PRIVATE** - Private
+ */
+#[Consumable(since: '32.0.0')]
+enum Preset: int {
+ /** @since 32.0.0 */
+ case LARGE = 9;
+ /** @since 32.0.0 */
+ case MEDIUM = 8;
+ /** @since 32.0.0 */
+ case SMALL = 7;
+ /** @since 32.0.0 */
+ case SHARED = 6;
+ /** @since 32.0.0 */
+ case UNIVERSITY = 5;
+ /** @since 32.0.0 */
+ case SCHOOL = 4;
+ /** @since 32.0.0 */
+ case CLUB = 3;
+ /** @since 32.0.0 */
+ case FAMILY = 2;
+ /** @since 32.0.0 */
+ case PRIVATE = 1;
+ /** @since 32.0.0 */
+ case NONE = 0;
+}
diff --git a/lib/public/Config/Lexicon/Strictness.php b/lib/public/Config/Lexicon/Strictness.php
new file mode 100644
index 00000000000..8136499cb3e
--- /dev/null
+++ b/lib/public/Config/Lexicon/Strictness.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP\Config\Lexicon;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+/**
+ * Strictness regarding using not-listed config keys
+ *
+ * - **Strictness::IGNORE** - fully ignore
+ * - **Strictness::NOTICE** - ignore and report
+ * - **Strictness::WARNING** - silently block (returns $default) and report
+ * - **Strictness::EXCEPTION** - block (throws exception) and report
+ */
+#[Consumable(since: '32.0.0')]
+enum Strictness {
+ /** @since 32.0.0 */
+ case IGNORE; // fully ignore
+ /** @since 32.0.0 */
+ case NOTICE; // ignore and report
+ /** @since 32.0.0 */
+ case WARNING; // silently block (returns $default) and report
+ /** @since 32.0.0 */
+ case EXCEPTION; // block (throws exception) and report
+}
diff --git a/lib/public/Config/ValueType.php b/lib/public/Config/ValueType.php
new file mode 100644
index 00000000000..32c734af32b
--- /dev/null
+++ b/lib/public/Config/ValueType.php
@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Config;
+
+use OCP\AppFramework\Attribute\Consumable;
+use OCP\Config\Exceptions\IncorrectTypeException;
+use OCP\IAppConfig;
+use UnhandledMatchError;
+
+/**
+ * Listing of available value type for typed config value
+ */
+#[Consumable(since: '32.0.0')]
+enum ValueType: int {
+ /**
+ * @since 32.0.0
+ */
+ case MIXED = 0;
+ /**
+ * @since 32.0.0
+ */
+ case STRING = 1;
+ /**
+ * @since 32.0.0
+ */
+ case INT = 2;
+ /**
+ * @since 32.0.0
+ */
+ case FLOAT = 3;
+ /**
+ * @since 32.0.0
+ */
+ case BOOL = 4;
+ /**
+ * @since 32.0.0
+ */
+ case ARRAY = 5;
+
+ /**
+ * get ValueType from string
+ *
+ * @param string $definition
+ *
+ * @return self
+ * @throws IncorrectTypeException
+ *
+ * @since 32.0.0
+ */
+ public static function fromStringDefinition(string $definition): self {
+ try {
+ return match ($definition) {
+ 'mixed' => self::MIXED,
+ 'string' => self::STRING,
+ 'int' => self::INT,
+ 'float' => self::FLOAT,
+ 'bool' => self::BOOL,
+ 'array' => self::ARRAY
+ };
+ } catch (\UnhandledMatchError) {
+ throw new IncorrectTypeException('unknown string definition');
+ }
+ }
+
+ /**
+ * get string definition for current enum value
+ *
+ * @return string
+ * @throws IncorrectTypeException
+ *
+ * @since 32.0.0
+ */
+ public function getDefinition(): string {
+ try {
+ return match ($this) {
+ self::MIXED => 'mixed',
+ self::STRING => 'string',
+ self::INT => 'int',
+ self::FLOAT => 'float',
+ self::BOOL => 'bool',
+ self::ARRAY => 'array',
+ };
+ } catch (UnhandledMatchError) {
+ throw new IncorrectTypeException('unknown type definition ' . $this->value);
+ }
+ }
+
+ /**
+ * get corresponding AppConfig flag value
+ *
+ * @return int
+ * @throws IncorrectTypeException
+ *
+ * @since 32.0.0
+ */
+ public function toAppConfigFlag(): int {
+ try {
+ return match ($this) {
+ self::MIXED => IAppConfig::VALUE_MIXED,
+ self::STRING => IAppConfig::VALUE_STRING,
+ self::INT => IAppConfig::VALUE_INT,
+ self::FLOAT => IAppConfig::VALUE_FLOAT,
+ self::BOOL => IAppConfig::VALUE_BOOL,
+ self::ARRAY => IAppConfig::VALUE_ARRAY,
+ };
+ } catch (UnhandledMatchError) {
+ throw new IncorrectTypeException('unknown type definition ' . $this->value);
+ }
+ }
+
+}
diff --git a/lib/public/Federation/ICloudIdManager.php b/lib/public/Federation/ICloudIdManager.php
index 03b6ced18f5..29e261ab3af 100644
--- a/lib/public/Federation/ICloudIdManager.php
+++ b/lib/public/Federation/ICloudIdManager.php
@@ -8,11 +8,14 @@ declare(strict_types=1);
*/
namespace OCP\Federation;
+use OCP\AppFramework\Attribute\Consumable;
+
/**
* Interface for resolving federated cloud ids
*
* @since 12.0.0
*/
+#[Consumable(since: '12.0.0')]
interface ICloudIdManager {
/**
* @param string $cloudId
@@ -55,4 +58,28 @@ interface ICloudIdManager {
* @since 30.0.0 - Optional parameter $httpsOnly was added
*/
public function removeProtocolFromUrl(string $url, bool $httpsOnly = false): string;
+
+ /**
+ * @param string $id The remote cloud id
+ * @param string $user The user id on the remote server
+ * @param string $remote The base address of the remote server
+ * @param ?string $displayName The displayname of the remote user
+ *
+ * @since 32.0.0
+ */
+ public function createCloudId(string $id, string $user, string $remote, ?string $displayName = null): ICloudId;
+
+ /**
+ * @param $resolver The cloud id resolver to register
+ *
+ * @since 32.0.0
+ */
+ public function registerCloudIdResolver(ICloudIdResolver $resolver): void;
+
+ /**
+ * @param $resolver The cloud id resolver to unregister
+ *
+ * @since 32.0.0
+ */
+ public function unregisterCloudIdResolver(ICloudIdResolver $resolver): void;
}
diff --git a/lib/public/Federation/ICloudIdResolver.php b/lib/public/Federation/ICloudIdResolver.php
new file mode 100644
index 00000000000..79f9ed11dd7
--- /dev/null
+++ b/lib/public/Federation/ICloudIdResolver.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Federation;
+
+use OCP\AppFramework\Attribute\Consumable;
+use OCP\AppFramework\Attribute\Implementable;
+
+/**
+ * Interface for resolving federated cloud ids
+ *
+ * @since 32.0.0
+ */
+#[Consumable(since: '32.0.0')]
+#[Implementable(since: '32.0.0')]
+interface ICloudIdResolver {
+ /**
+ * @param string $cloudId
+ * @return ICloudId
+ * @throws \InvalidArgumentException
+ *
+ * @since 32.0.0
+ */
+ public function resolveCloudId(string $cloudId): ICloudId;
+
+ /**
+ * Check if the input is a correctly formatted cloud id
+ *
+ * @param string $cloudId
+ * @return bool
+ *
+ * @since 32.0.0
+ */
+ public function isValidCloudId(string $cloudId): bool;
+}
generated by cgit v1.2.3 (git 2.39.1) at 2025-07-28 21:46:33 +0000