Merge pull request #49567 from nextcloud/debt/noid/experimental-annotation-for-userconfig

chore: mark userconfig as experimental
2 years ago · a4502b08b5
parent 863c8808e0 4fba2aec35
commit a4502b08b5
2 changed files with 97 additions and 2 deletions
--- a/lib/unstable/Config/IUserConfig.php
+++ b/lib/unstable/Config/IUserConfig.php
@ -31,9 +31,15 @@ use NCU\Config\Exceptions\UnknownKeyException;
 * @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

 	/**
@ -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;
@ -58,6 +66,8 @@ interface IUserConfig {
 	 * @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;
@ -72,6 +82,8 @@ interface IUserConfig {
 	 * @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;
@ -85,6 +97,8 @@ interface IUserConfig {
 	 * @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;
@ -99,6 +113,8 @@ interface IUserConfig {
 	 *
 	 * @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;
@ -118,6 +134,8 @@ interface IUserConfig {
 	 *
 	 * @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;
@ -134,6 +152,8 @@ interface IUserConfig {
 	 * @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;
@ -150,6 +170,8 @@ interface IUserConfig {
 	 * @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;
@ -164,6 +186,8 @@ interface IUserConfig {
 	 * @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;
@ -178,6 +202,8 @@ interface IUserConfig {
 	 * @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;
@ -194,6 +220,8 @@ interface IUserConfig {
 	 * @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;
@ -210,6 +238,8 @@ interface IUserConfig {
 	 * @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;
@ -225,6 +255,8 @@ interface IUserConfig {
 	 * @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;
@ -240,6 +272,8 @@ interface IUserConfig {
 	 * @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;
@ -255,6 +289,8 @@ interface IUserConfig {
 	 * @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;
@ -271,7 +307,10 @@ interface IUserConfig {
 	 * @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()
@ -292,7 +331,10 @@ interface IUserConfig {
 	 * @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()
@ -313,7 +355,10 @@ interface IUserConfig {
 	 * @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()
@ -334,7 +379,10 @@ interface IUserConfig {
 	 * @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()
@ -355,7 +403,10 @@ interface IUserConfig {
 	 * @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()
@ -378,6 +429,8 @@ interface IUserConfig {
 	 * @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;
@ -396,6 +449,8 @@ interface IUserConfig {
 	 * @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;
@ -416,7 +471,10 @@ interface IUserConfig {
 	 * @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()
@ -446,7 +504,10 @@ interface IUserConfig {
 	 * @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()
@ -471,7 +532,10 @@ interface IUserConfig {
 	 * @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()
@ -495,7 +559,10 @@ interface IUserConfig {
 	 * @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()
@ -520,7 +587,10 @@ interface IUserConfig {
 	 * @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()
@ -540,6 +610,8 @@ interface IUserConfig {
 	 * @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;
@ -553,6 +625,7 @@ interface IUserConfig {
 	 * @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;
@ -569,6 +642,8 @@ interface IUserConfig {
 	 * @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;
@ -581,6 +656,8 @@ interface IUserConfig {
 	 * @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;
@ -594,6 +671,8 @@ interface IUserConfig {
 	 * @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;
@ -606,6 +685,8 @@ interface IUserConfig {
 	 * @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;
@ -631,6 +712,8 @@ interface IUserConfig {
 	 *
 	 * @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;
@ -642,6 +725,7 @@ interface IUserConfig {
 	 * @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;
@ -652,6 +736,7 @@ interface IUserConfig {
 	 * @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;
@ -660,6 +745,8 @@ interface IUserConfig {
 	 * 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;
@ -668,6 +755,8 @@ interface IUserConfig {
 	 * 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;
@ -680,6 +769,7 @@ interface IUserConfig {
 	 * @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;
@ -688,6 +778,7 @@ interface IUserConfig {
 	 * 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;
--- a/lib/unstable/Config/ValueType.php
+++ b/lib/unstable/Config/ValueType.php
@ -38,6 +38,8 @@ enum ValueType: int {
 	 *
 	 * @return self
 	 * @throws IncorrectTypeException
+	 *
+	 * @experimental 31.0.0
 	 * @since 31.0.0
 	 */
 	public static function fromStringDefinition(string $definition): self {
@ -60,6 +62,8 @@ enum ValueType: int {
 	 *
 	 * @return string
 	 * @throws IncorrectTypeException
+	 *
+	 * @experimental 31.0.0
 	 * @since 31.0.0
 	 */
 	public function getDefinition(): string {