Skip to content

Commit

Permalink
Merge pull request #49567 from nextcloud/debt/noid/experimental-annot…
Browse files Browse the repository at this point in the history 
…ation-for-userconfig

chore: mark userconfig as experimental
  • Loading branch information
@nickvergessen
nickvergessen authored Nov 29, 2024
2 parents 863c880 + 4fba2ae commit a4502b0
Show file tree
Hide file tree
Showing 2 changed files with 97 additions and 2 deletions.
95 changes: 93 additions & 2 deletions lib/unstable/Config/IUserConfig.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,15 @@
* @since 31.0.0
*/
interface IUserConfig {
/** @since 31.0.0 */
/**
* @experimental 31.0.0
* @since 31.0.0
*/
public const FLAG_SENSITIVE = 1; // value is sensitive
/** @since 31.0.0 */
/**
* @experimental 31.0.0
* @since 31.0.0
*/
public const FLAG_INDEXED = 2; // value should be indexed

/**
Expand All @@ -45,6 +51,8 @@ interface IUserConfig {
* @param string $appId optional id of app
*
* @return list<string> list of userIds
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getUserIds(string $appId = ''): array;
Expand All @@ -58,6 +66,8 @@ public function getUserIds(string $appId = ''): array;
* @param string $userId id of the user
*
* @return list<string> list of app ids
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getApps(string $userId): array;
Expand All @@ -72,6 +82,8 @@ public function getApps(string $userId): array;
* @param string $app id of the app
*
* @return list<string> list of stored config keys
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getKeys(string $userId, string $app): array;
Expand All @@ -85,6 +97,8 @@ public function getKeys(string $userId, string $app): array;
* @param bool $lazy search within lazy loaded config
*
* @return bool TRUE if key exists
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function hasKey(string $userId, string $app, string $key, ?bool $lazy = false): bool;
Expand All @@ -99,6 +113,8 @@ public function hasKey(string $userId, string $app, string $key, ?bool $lazy = f
*
* @return bool TRUE if value is sensitive
* @throws UnknownKeyException if config key is not known
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function isSensitive(string $userId, string $app, string $key, ?bool $lazy = false): bool;
Expand All @@ -118,6 +134,8 @@ public function isSensitive(string $userId, string $app, string $key, ?bool $laz
*
* @return bool TRUE if value is sensitive
* @throws UnknownKeyException if config key is not known
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function isIndexed(string $userId, string $app, string $key, ?bool $lazy = false): bool;
Expand All @@ -134,6 +152,8 @@ public function isIndexed(string $userId, string $app, string $key, ?bool $lazy
* @return bool TRUE if config is lazy loaded
* @throws UnknownKeyException if config key is not known
* @see IUserConfig for details about lazy loading
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function isLazy(string $userId, string $app, string $key): bool;
Expand All @@ -150,6 +170,8 @@ public function isLazy(string $userId, string $app, string $key): bool;
* @param bool $filtered filter sensitive config values
*
* @return array<string, string|int|float|bool|array> [key => value]
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getValues(string $userId, string $app, string $prefix = '', bool $filtered = false): array;
Expand All @@ -164,6 +186,8 @@ public function getValues(string $userId, string $app, string $prefix = '', bool
* @param bool $filtered filter sensitive config values
*
* @return array<string, string|int|float|bool|array> [key => value]
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getAllValues(string $userId, bool $filtered = false): array;
Expand All @@ -178,6 +202,8 @@ public function getAllValues(string $userId, bool $filtered = false): array;
* @param ValueType|null $typedAs enforce type for the returned values
*
* @return array<string, string|int|float|bool|array> [appId => value]
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getValuesByApps(string $userId, string $key, bool $lazy = false, ?ValueType $typedAs = null): array;
Expand All @@ -194,6 +220,8 @@ public function getValuesByApps(string $userId, string $key, bool $lazy = false,
* @param array|null $userIds limit the search to a list of user ids
*
* @return array<string, string|int|float|bool|array> [userId => value]
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getValuesByUsers(string $app, string $key, ?ValueType $typedAs = null, ?array $userIds = null): array;
Expand All @@ -210,6 +238,8 @@ public function getValuesByUsers(string $app, string $key, ?ValueType $typedAs =
* @param bool $caseInsensitive non-case-sensitive search, only works if $value is a string
*
* @return Generator<string>
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function searchUsersByValueString(string $app, string $key, string $value, bool $caseInsensitive = false): Generator;
Expand All @@ -225,6 +255,8 @@ public function searchUsersByValueString(string $app, string $key, string $value
* @param int $value config value
*
* @return Generator<string>
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function searchUsersByValueInt(string $app, string $key, int $value): Generator;
Expand All @@ -240,6 +272,8 @@ public function searchUsersByValueInt(string $app, string $key, int $value): Gen
* @param array $values list of possible config values
*
* @return Generator<string>
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function searchUsersByValues(string $app, string $key, array $values): Generator;
Expand All @@ -255,6 +289,8 @@ public function searchUsersByValues(string $app, string $key, array $values): Ge
* @param bool $value config value
*
* @return Generator<string>
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function searchUsersByValueBool(string $app, string $key, bool $value): Generator;
Expand All @@ -271,7 +307,10 @@ public function searchUsersByValueBool(string $app, string $key, bool $value): G
* @param bool $lazy search within lazy loaded config
*
* @return string stored config value or $default if not set in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserConfig for explanation about lazy loading
* @see getValueInt()
* @see getValueFloat()
Expand All @@ -292,7 +331,10 @@ public function getValueString(string $userId, string $app, string $key, string
* @param bool $lazy search within lazy loaded config
*
* @return int stored config value or $default if not set in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserConfig for explanation about lazy loading
* @see getValueString()
* @see getValueFloat()
Expand All @@ -313,7 +355,10 @@ public function getValueInt(string $userId, string $app, string $key, int $defau
* @param bool $lazy search within lazy loaded config
*
* @return float stored config value or $default if not set in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserConfig for explanation about lazy loading
* @see getValueString()
* @see getValueInt()
Expand All @@ -334,7 +379,10 @@ public function getValueFloat(string $userId, string $app, string $key, float $d
* @param bool $lazy search within lazy loaded config
*
* @return bool stored config value or $default if not set in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserPrefences for explanation about lazy loading
* @see getValueString()
* @see getValueInt()
Expand All @@ -355,7 +403,10 @@ public function getValueBool(string $userId, string $app, string $key, bool $def
* @param bool $lazy search within lazy loaded config
*
* @return array stored config value or $default if not set in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserConfig for explanation about lazy loading
* @see getValueString()
* @see getValueInt()
Expand All @@ -378,6 +429,8 @@ public function getValueArray(string $userId, string $app, string $key, array $d
* @return ValueType type of the value
* @throws UnknownKeyException if config key is not known
* @throws IncorrectTypeException if config value type is not known
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getValueType(string $userId, string $app, string $key, ?bool $lazy = null): ValueType;
Expand All @@ -396,6 +449,8 @@ public function getValueType(string $userId, string $app, string $key, ?bool $la
* @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
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getValueFlags(string $userId, string $app, string $key, bool $lazy = false): int;
Expand All @@ -416,7 +471,10 @@ public function getValueFlags(string $userId, string $app, string $key, bool $la
* @param bool $lazy set config as lazy loaded
*
* @return bool TRUE if value was different, therefor updated in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserConfig for explanation about lazy loading
* @see setValueInt()
* @see setValueFloat()
Expand Down Expand Up @@ -446,7 +504,10 @@ public function setValueString(string $userId, string $app, string $key, string
* @param bool $lazy set config as lazy loaded
*
* @return bool TRUE if value was different, therefor updated in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserConfig for explanation about lazy loading
* @see setValueString()
* @see setValueFloat()
Expand All @@ -471,7 +532,10 @@ public function setValueInt(string $userId, string $app, string $key, int $value
* @param bool $lazy set config as lazy loaded
*
* @return bool TRUE if value was different, therefor updated in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserConfig for explanation about lazy loading
* @see setValueString()
* @see setValueInt()
Expand All @@ -495,7 +559,10 @@ public function setValueFloat(string $userId, string $app, string $key, float $v
* @param bool $lazy set config as lazy loaded
*
* @return bool TRUE if value was different, therefor updated in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserConfig for explanation about lazy loading
* @see setValueString()
* @see setValueInt()
Expand All @@ -520,7 +587,10 @@ public function setValueBool(string $userId, string $app, string $key, bool $val
* @param bool $lazy set config as lazy loaded
*
* @return bool TRUE if value was different, therefor updated in database
*
* @experimental 31.0.0
* @since 31.0.0
*
* @see IUserConfig for explanation about lazy loading
* @see setValueString()
* @see setValueInt()
Expand All @@ -540,6 +610,8 @@ public function setValueArray(string $userId, string $app, string $key, array $v
* @param bool $sensitive TRUE to set as sensitive, FALSE to unset
*
* @return bool TRUE if database update were necessary
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function updateSensitive(string $userId, string $app, string $key, bool $sensitive): bool;
Expand All @@ -553,6 +625,7 @@ public function updateSensitive(string $userId, string $app, string $key, bool $
* @param string $key config key
* @param bool $sensitive TRUE to set as sensitive, FALSE to unset
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function updateGlobalSensitive(string $app, string $key, bool $sensitive): void;
Expand All @@ -569,6 +642,8 @@ public function updateGlobalSensitive(string $app, string $key, bool $sensitive)
* @param bool $indexed TRUE to set as indexed, FALSE to unset
*
* @return bool TRUE if database update were necessary
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function updateIndexed(string $userId, string $app, string $key, bool $indexed): bool;
Expand All @@ -581,6 +656,8 @@ public function updateIndexed(string $userId, string $app, string $key, bool $in
* @param string $app id of the app
* @param string $key config key
* @param bool $indexed TRUE to set as indexed, FALSE to unset
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function updateGlobalIndexed(string $app, string $key, bool $indexed): void;
Expand All @@ -594,6 +671,8 @@ public function updateGlobalIndexed(string $app, string $key, bool $indexed): vo
* @param bool $lazy TRUE to set as lazy loaded, FALSE to unset
*
* @return bool TRUE if database update was necessary
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function updateLazy(string $userId, string $app, string $key, bool $lazy): bool;
Expand All @@ -606,6 +685,8 @@ public function updateLazy(string $userId, string $app, string $key, bool $lazy)
* @param string $app id of the app
* @param string $key config key
* @param bool $lazy TRUE to set as lazy loaded, FALSE to unset
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function updateGlobalLazy(string $app, string $key, bool $lazy): void;
Expand All @@ -631,6 +712,8 @@ public function updateGlobalLazy(string $app, string $key, bool $lazy): void;
*
* @return array
* @throws UnknownKeyException if config key is not known in database
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function getDetails(string $userId, string $app, string $key): array;
Expand All @@ -642,6 +725,7 @@ public function getDetails(string $userId, string $app, string $key): array;
* @param string $app id of the app
* @param string $key config key
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function deleteUserConfig(string $userId, string $app, string $key): void;
Expand All @@ -652,6 +736,7 @@ public function deleteUserConfig(string $userId, string $app, string $key): void
* @param string $app id of the app
* @param string $key config key
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function deleteKey(string $app, string $key): void;
Expand All @@ -660,6 +745,8 @@ public function deleteKey(string $app, string $key): void;
* delete all config keys linked to an app
*
* @param string $app id of the app
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function deleteApp(string $app): void;
Expand All @@ -668,6 +755,8 @@ public function deleteApp(string $app): void;
* delete all config keys linked to a user
*
* @param string $userId id of the user
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function deleteAllUserConfig(string $userId): void;
Expand All @@ -680,6 +769,7 @@ public function deleteAllUserConfig(string $userId): void;
* @param string $userId id of the user
* @param bool $reload set to TRUE to refill cache instantly after clearing it
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function clearCache(string $userId, bool $reload = false): void;
Expand All @@ -688,6 +778,7 @@ 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.
*
* @experimental 31.0.0
* @since 31.0.0
*/
public function clearCacheAll(): void;
Expand Down
Loading

0 comments on commit a4502b0

Please sign in to comment.