UserConfig
Added in version 31.
Since v31, Nextcloud includes a new API to manage users’ preferences.
Concept overview
Nextcloud includes an API to store and access users configuration values.
On top of storing and accessing your configuration values, IUserConfig
comes with different concepts:
Typed Config Values
To ensure better stability of your code, config values are typed enforced. Type is set only once, at creation in database, and cannot be changed.
Note
Value stored before Nextcloud 31 are automatically typed as mixed. However, it is not possible to manually set a value as mixed.
Value not set as mixed must be retrieved using the corresponding method.
Values Sensitivity
When storing a new config value, it can be set as sensitive. Configuration values set as sensitive are hidden from system reports and stored encrypted in the database.
setValueString(
'user',
'myapp',
'mykey',
'myvalue',
flags: IUserConfig::FLAG_SENSITIVE
);
Note
Once set as sensitive, it can only be reverted using updateSensitive()
/updateGlobalSensitive()
Indexed values
If a search on config value is expected, it can be set as indexed.
setValueString(
'user',
'myapp',
'mykey',
'myvalue',
flags: IUserConfig::FLAG_INDEXED
);
Note
Configuration values set as indexed are stored in an indexed field in the database with a limited length of 64 characters.
Lazy Loading
To lighten the loading of user configuration, you have the possibility to set config values as lazy. All lazy configuration values are loaded from the database once one is read.
setValueString(
'user',
'myapp',
'mykey',
'myvalue',
lazy: true
);
Note
Flag as lazy as much ‘large block of text’ entries (json, key pairs, …) as possible,
flag as lazy entries that are needed on quiet endpoints,
do not flag as lazy part of code that might be called during the global loading of all pages.
Retrieving the configuration value will require to specify the fact that it is stored as lazy.
getValueString(
'user',
'myapp',
'mykey',
'default',
lazy: true
);
Consuming the UserConfig API
To consume the API, you first need to inject \OCP\IUserConfig
Storing a config value
API provide multiple methods to store a config value, based on its type. The global behavior for each of those methods is to call them using:
user id (string)
app id (string),
config key (string),
config value,
lazy flag (boolean),
flags (int)
The returned boolean will be true if an update of the database were needed.
setValueString(string $userId, string $app, string $key, string $value, bool $lazy, int $flags)
setValueInt(string $userId, string $app, string $key, int $value, bool $lazy, int $flags)
setValueFloat(string $userId, string $app, string $key, float $value, bool $lazy, int $flags)
setValueBool(string $userId, string $app, string $key, bool $value, bool $lazy, int $flags)
setValueArray(string $userId, string $app, string $key, array $value, bool $lazy, int $flags)
Retrieving a config value
Configuration values are to be retrieved using one of the return typed method from the list:
getValueString(string $userId, string $app, string $key, string $default, bool $lazy)
getValueInt(string $userId, string $app, string $key, int $default, bool $lazy)
getValueFloat(string $userId, string $app, string $key, float $default, bool $lazy)
getValueBool(string $userId, string $app, string $key, bool $default, bool $lazy)
getValueArray(string $userId, string $app, string $key, array $default, bool $lazy)
Managing config keys
getUserIds(string $appId)
returns list of users with stored configuration values for an app
getApps(string $userId)
returns list of apps with stored configuration values for a user
getKeys(string $userId, string $app)
returns list of stored configuration keys for a user and an app
hasKey(string $userId, string $app, string $key, ?bool $lazy)
returns TRUE if key can be found
isSensitive(string $userId, string $app, string $key, ?bool $lazy)
returns TRUE if value is set as sensitive
isIndexed(string $userId, string $app, string $key, ?bool $lazy)
returns TRUE if value is set as indexed
isLazy(string $userId, string $app, string $key)
returns TRUE if value is set as lazy
updateSensitive(string $userId, string $app, string $key, bool $sensitive)
update sensitive status of a configuration value for a specific user
updateGlobalSensitive(string $app, string $key, bool $sensitive)
update sensitive status of a configuration value for all users
updateIndexed(string $userId, string $app, string $key, bool $sensitive)
update indexed status of a configuration value for a specific user
updateGlobalIndexed(string $app, string $key, bool $sensitive)
update indexed status of a configuration value for all users
updateLazy(string $userId, string $app, string $key, bool $lazy)
update lazy status of a configuration value for a specific user
updateGlobalLazy(string $app, string $key, bool $lazy)
update lazy status of a configuration value for all users
getValueType(string $userId, string $app, string $key, bool $lazy)
returns bitflag defining the type of a configuration value
getValueFlags(string $userId, string $app, string $key, bool $lazy)
returns bitflag defining the flags of a configuration value
deleteUserConfig(string $userId, string $app, string $key)
delete a config key and its value for a user
deleteAllUserConfig(string $userId)
delete all config values for a single user
deleteKey(string $app, string $key)
delete a config key and its value for all users
deleteKey(string $app, string $key)
delete a config key and its value for all users
deleteApp(string $app)
delete all config keys from an app for all users
Note
Some method allows $lazy
to be null
, meaning that the search will be extended to all configuration values, lazy or not.
Miscellaneous
API also provide extra tools for broaded uses
getValues(string $userId, string $app, string $prefix, bool $filtered)
returns all stored configuration values.$filtered
can be set to TRUE to hide _sensitive_ values in the returned array
getAllValues(string $userId, bool $filtered)
returns all stored configuration values.$filtered
can be set to TRUE to hide _sensitive_ values in the returned array
getValuesByApps(string $userId, string $key, bool $lazy, ?ValueType $typedAs)
returns all stored configuration values per apps, based on a specific config key.
getValuesByUsers(string $app, string $key, ?ValueType $typedAs, array $userIds)
returns all stored configuration values per users, based on a specific config key.
searchUsersByValueString(string $app, string $key, string $value, bool $caseInsensitive)
returns list of users with a config key set to a specific value.
searchUsersByValues(string $app, string $key, array $values)
returns list of users with a config key set to a value from a list.
searchUsersByValueInt(string $app, string $key, string $value)
returns list of users with a config key set to a specific value.
searchUsersByValueBool(string $app, string $key, string $value)
returns list of users with a config key set to a specific value.
getDetails(string $userId, string $app, string $key)
get all details about a configuration key.
clearCache(string $userId, bool $reload)
clear internal cache for a specific user
clearCacheAll()
clear all internal cache