Skip to content

Commit d0bdc8e

Browse files
rakeknivenrakekniven
authored
Merge pull request #12843 from nextcloud/backport/12840/stable31
[stable31] IUserConfig
2 parents 938364f + d26e2fc commit d0bdc8e

File tree

2 files changed

+184
-0
lines changed

2 files changed

+184
-0
lines changed

‎developer_manual/digging_deeper/config/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ Config & Preferences
66
:maxdepth: 2
77

88
appconfig
9+
userconfig

‎developer_manual/digging_deeper/config/userconfig.rst‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
==========
2+
UserConfig
3+
==========
4+
5+
.. versionadded:: 31
6+
7+
Since v31, Nextcloud includes a new API to manage users' preferences.
8+
9+
10+
Concept overview
11+
----------------
12+
13+
Nextcloud includes an API to store and access users configuration values.
14+
On top of storing and accessing your configuration values, ``IUserConfig`` comes with different concepts:
15+
16+
.. _userconfig_concepts:
17+
18+
Typed Config Values
19+
^^^^^^^^^^^^^^^^^^^
20+
21+
To ensure better stability of your code, config values are typed enforced.
22+
Type is set only once, at creation in database, and cannot be changed.
23+
24+
.. note::
25+
- Value stored before Nextcloud 31 are automatically typed as `mixed`. However, it is not possible to manually set a value as `mixed`.
26+
- Value not set as `mixed` must be retrieved using the corresponding method.
27+
28+
Values Sensitivity
29+
^^^^^^^^^^^^^^^^^^
30+
31+
When storing a new config value, it can be set as `sensitive`.
32+
Configuration values set as `sensitive` are hidden from system reports and stored encrypted in the database.
33+
34+
.. code-block:: php
35+
36+
setValueString(
37+
'user',
38+
'myapp',
39+
'mykey',
40+
'myvalue',
41+
flags: IUserConfig::FLAG_SENSITIVE
42+
);
43+
44+
.. note::
45+
Once set as `sensitive`, it can only be reverted using ``updateSensitive()``/``updateGlobalSensitive()``
46+
47+
Indexed values
48+
^^^^^^^^^^^^^^
49+
50+
If a search on config value is expected, it can be set as `indexed`.
51+
52+
.. code-block:: php
53+
54+
setValueString(
55+
'user',
56+
'myapp',
57+
'mykey',
58+
'myvalue',
59+
flags: IUserConfig::FLAG_INDEXED
60+
);
61+
62+
.. note::
63+
Configuration values set as `indexed` are stored in an indexed field in the database with a limited length of 64 characters.
64+
65+
66+
Lazy Loading
67+
^^^^^^^^^^^^
68+
69+
To lighten the loading of user configuration, you have the possibility to set config values as `lazy`.
70+
All `lazy` configuration values are loaded from the database once one is read.
71+
72+
.. code-block:: php
73+
74+
setValueString(
75+
'user',
76+
'myapp',
77+
'mykey',
78+
'myvalue',
79+
lazy: true
80+
);
81+
82+
.. note::
83+
- Flag as `lazy` as much 'large block of text' entries (json, key pairs, ...) as possible,
84+
- flag as `lazy` entries that are needed on quiet endpoints,
85+
- do **not** flag as `lazy` part of code that might be called during the global loading of all pages.
86+
87+
88+
Retrieving the configuration value will require to specify the fact that it is stored as `lazy`.
89+
90+
.. code-block:: php
91+
92+
getValueString(
93+
'user',
94+
'myapp',
95+
'mykey',
96+
'default',
97+
lazy: true
98+
);
99+
100+
Consuming the UserConfig API
101+
----------------------------
102+
103+
To consume the API, you first need to :ref:`inject<dependency-injection>` ``\OCP\IUserConfig``
104+
105+
106+
Storing a config value
107+
^^^^^^^^^^^^^^^^^^^^^^
108+
109+
API provide multiple methods to store a config value, based on its type.
110+
The global behavior for each of those methods is to call them using:
111+
112+
- user id (string)
113+
- app id (string),
114+
- config key (string),
115+
- config value,
116+
- lazy flag (boolean),
117+
- flags (int)
118+
119+
The returned boolean will be true if an update of the database were needed.
120+
121+
* ``setValueString(string $userId, string $app, string $key, string $value, bool $lazy, int $flags)``
122+
* ``setValueInt(string $userId, string $app, string $key, int $value, bool $lazy, int $flags)``
123+
* ``setValueFloat(string $userId, string $app, string $key, float $value, bool $lazy, int $flags)``
124+
* ``setValueBool(string $userId, string $app, string $key, bool $value, bool $lazy, int $flags)``
125+
* ``setValueArray(string $userId, string $app, string $key, array $value, bool $lazy, int $flags)``
126+
127+
128+
Retrieving a config value
129+
^^^^^^^^^^^^^^^^^^^^^^^^^
130+
131+
Configuration values are to be retrieved using one of the return typed method from the list:
132+
133+
* ``getValueString(string $userId, string $app, string $key, string $default, bool $lazy)``
134+
* ``getValueInt(string $userId, string $app, string $key, int $default, bool $lazy)``
135+
* ``getValueFloat(string $userId, string $app, string $key, float $default, bool $lazy)``
136+
* ``getValueBool(string $userId, string $app, string $key, bool $default, bool $lazy)``
137+
* ``getValueArray(string $userId, string $app, string $key, array $default, bool $lazy)``
138+
139+
140+
Managing config keys
141+
^^^^^^^^^^^^^^^^^^^^
142+
143+
* ``getUserIds(string $appId)`` returns list of users with stored configuration values for an app
144+
* ``getApps(string $userId)`` returns list of apps with stored configuration values for a user
145+
* ``getKeys(string $userId, string $app)`` returns list of stored configuration keys for a user and an app
146+
* ``hasKey(string $userId, string $app, string $key, ?bool $lazy)`` returns TRUE if key can be found
147+
* ``isSensitive(string $userId, string $app, string $key, ?bool $lazy)`` returns TRUE if value is set as `sensitive`
148+
* ``isIndexed(string $userId, string $app, string $key, ?bool $lazy)`` returns TRUE if value is set as `indexed`
149+
* ``isLazy(string $userId, string $app, string $key)`` returns TRUE if value is set as `lazy`
150+
* ``updateSensitive(string $userId, string $app, string $key, bool $sensitive)`` update `sensitive` status of a configuration value for a specific user
151+
* ``updateGlobalSensitive(string $app, string $key, bool $sensitive)`` update `sensitive` status of a configuration value for all users
152+
* ``updateIndexed(string $userId, string $app, string $key, bool $sensitive)`` update `indexed` status of a configuration value for a specific user
153+
* ``updateGlobalIndexed(string $app, string $key, bool $sensitive)`` update `indexed` status of a configuration value for all users
154+
* ``updateLazy(string $userId, string $app, string $key, bool $lazy)`` update `lazy` status of a configuration value for a specific user
155+
* ``updateGlobalLazy(string $app, string $key, bool $lazy)`` update `lazy` status of a configuration value for all users
156+
* ``getValueType(string $userId, string $app, string $key, bool $lazy)`` returns bitflag defining the type of a configuration value
157+
* ``getValueFlags(string $userId, string $app, string $key, bool $lazy)`` returns bitflag defining the flags of a configuration value
158+
* ``deleteUserConfig(string $userId, string $app, string $key)`` delete a config key and its value for a user
159+
* ``deleteAllUserConfig(string $userId)`` delete all config values for a single user
160+
* ``deleteKey(string $app, string $key)`` delete a config key and its value for all users
161+
* ``deleteKey(string $app, string $key)`` delete a config key and its value for all users
162+
* ``deleteApp(string $app)`` delete all config keys from an app for all users
163+
164+
.. note::
165+
Some method allows ``$lazy`` to be ``null``, meaning that the search will be extended to all configuration values, `lazy` or not.
166+
167+
Miscellaneous
168+
^^^^^^^^^^^^^
169+
170+
API also provide extra tools for broaded uses
171+
172+
* ``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
173+
* ``getAllValues(string $userId, bool $filtered)`` returns all stored configuration values. ``$filtered`` can be set to TRUE to hide _sensitive_ values in the returned array
174+
* ``getValuesByApps(string $userId, string $key, bool $lazy, ?ValueType $typedAs)`` returns all stored configuration values per apps, based on a specific config key.
175+
* ``getValuesByUsers(string $app, string $key, ?ValueType $typedAs, array $userIds)`` returns all stored configuration values per users, based on a specific config key.
176+
* ``searchUsersByValueString(string $app, string $key, string $value, bool $caseInsensitive)`` returns list of users with a config key set to a specific value.
177+
* ``searchUsersByValues(string $app, string $key, array $values)`` returns list of users with a config key set to a value from a list.
178+
* ``searchUsersByValueInt(string $app, string $key, string $value)`` returns list of users with a config key set to a specific value.
179+
* ``searchUsersByValueBool(string $app, string $key, string $value)`` returns list of users with a config key set to a specific value.
180+
* ``getDetails(string $userId, string $app, string $key)`` get all details about a configuration key.
181+
* ``clearCache(string $userId, bool $reload)`` clear internal cache for a specific user
182+
* ``clearCacheAll()`` clear all internal cache
183+

0 commit comments

Comments
 (0)