diff --git a/developer_manual/digging_deeper/config/index.rst b/developer_manual/digging_deeper/config/index.rst index e55342c3c..073df43f6 100644 --- a/developer_manual/digging_deeper/config/index.rst +++ b/developer_manual/digging_deeper/config/index.rst @@ -6,3 +6,4 @@ Config & Preferences :maxdepth: 2 appconfig + userconfig diff --git a/developer_manual/digging_deeper/config/userconfig.rst b/developer_manual/digging_deeper/config/userconfig.rst new file mode 100644 index 000000000..947ef7e50 --- /dev/null +++ b/developer_manual/digging_deeper/config/userconfig.rst @@ -0,0 +1,183 @@ +========== +UserConfig +========== + +.. versionadded:: 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: + +.. _userconfig_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. + +.. code-block:: php + + 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`. + +.. code-block:: php + + 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. + +.. code-block:: php + + 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`. + +.. code-block:: php + + getValueString( + 'user', + 'myapp', + 'mykey', + 'default', + lazy: true + ); + +Consuming the UserConfig API +---------------------------- + +To consume the API, you first need to :ref:`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 +