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