Skip to content

Commit 845fb9a

Browse files
ArtificialOwlArtificialOwl
authored
Merge pull request #11617 from nextcloud/docs/appconfig-api-29
appconfg api
2 parents 8a4ea3e + b2c9012 commit 845fb9a

File tree

5 files changed

+177
-1
lines changed

5 files changed

+177
-1
lines changed

‎admin_manual/configuration_server/occ_command.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -341,6 +341,21 @@ The ``config`` commands are used to configure the Nextcloud server::
341341
config:system:get Get a system config value
342342
config:system:set Set a system config value
343343

344+
345+
While setting a configuration value, multiple options are available:
346+
347+
- ``--value=VALUE`` change the configuration value
348+
- ``--type=TYPE`` change the type of the value. Use carefully; can break your instance
349+
- ``--lazy|--no-lazy`` set value as `lazy`
350+
- ``--sensitive|--no-sensitive`` set value as `sensitive`
351+
- ``--update-only`` only updates if a value is already stored
352+
353+
.. note::
354+
See `Appconfig Concepts`_ to learn more about `typed value`, `lazy` and `sensitive` flag.
355+
356+
.. _Appconfig Concepts: https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/config/appconfig.html#concept-overview
357+
358+
344359
You can list all configuration values with one command::
345360

346361
sudo -u www-data php occ config:list

‎developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_29.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Added APIs
2929
Changed APIs
3030
^^^^^^^^^^^^
3131

32-
* tbd
32+
* `IAppConfig` has been fully reworked, most of previous methods are now deprecated. The new version of the API implements multiple settings for app config values to define their laziness and sensitivity.
3333

3434
Deprecated APIs
3535
^^^^^^^^^^^^^^^

‎developer_manual/digging_deeper/config/appconfig.rst

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
=========
2+
AppConfig
3+
=========
4+
5+
.. versionadded:: 29
6+
7+
Since v29, Nextcloud includes a new API to manage your app configuration.
8+
9+
10+
Concept overview
11+
----------------
12+
13+
Nextcloud includes an API to store and access your app configuration values.
14+
On top of storing and accessing your configuration values, ``IAppConfig`` comes with different concepts:
15+
16+
.. _appconfig_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 29 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+
'myapp',
38+
'mykey',
39+
'myvalue',
40+
sensitive: true
41+
);
42+
43+
.. note::
44+
Once set as `sensitive`, it can only be reverted using ``updateSensitive()``
45+
46+
47+
Lazy Loading
48+
^^^^^^^^^^^^
49+
50+
To lighten the loading of all apps configuration at load, you have the possibility to set config values as `lazy`.
51+
All `lazy` configuration values are loaded from the database once one is read.
52+
53+
.. code-block:: php
54+
55+
setValueString(
56+
'myapp',
57+
'mykey',
58+
'myvalue',
59+
lazy: true
60+
);
61+
62+
.. note::
63+
- Flag as `lazy` as much 'large block of text' entries (json, key pairs, ...) as possible,
64+
- flag as `lazy` entries that are needed on quiet endpoints,
65+
- do **not** flag as `lazy` part of code that might be called during the global loading of the instance and its apps.
66+
67+
68+
Retrieving the configuration value will require to specify the fact that it is stored as `lazy`.
69+
70+
.. code-block:: php
71+
72+
getValueString(
73+
'myapp',
74+
'mykey',
75+
'default',
76+
lazy: true
77+
);
78+
79+
.. note::
80+
- Requesting with ``1azy: false`` will returns the default value if configuration value is stored as `lazy`.
81+
- Requesting with ``lazy: true`` will returns the correct value even if configuration value is stored as `non-lazy (as there is a huge probability that the `non-lazy` value are already loaded)
82+
83+
Consuming the AppConfig API
84+
---------------------------
85+
86+
To consume the API, you first need to :ref:`inject<dependency-injection>` ``\OCP\IAppConfig``
87+
88+
89+
Storing a config value
90+
^^^^^^^^^^^^^^^^^^^^^^
91+
92+
API provide multiple methods to store a config value, based on its type.
93+
The global behavior for each of those methods is to call them using:
94+
95+
- app id (string),
96+
- config key (string),
97+
- config value,
98+
- lazy flag (boolean),
99+
- sensitivity flag (boolean)
100+
101+
The returned boolean will be true if an update of the database were needed.
102+
103+
* ``setValueString(string $app, string $key, string $value, bool $lazy, bool $sensitive)``
104+
* ``setValueInt(string $app, string $key, int $value, bool $lazy, bool $sensitive)``
105+
* ``setValueFloat(string $app, string $key, float $value, bool $lazy, bool $sensitive)``
106+
* ``setValueBool(string $app, string $key, bool $value, bool $lazy)``
107+
* ``setValueArray(string $app, string $key, array $value, bool $lazy, bool $sensitive)``
108+
109+
110+
Retrieving a config value
111+
^^^^^^^^^^^^^^^^^^^^^^^^^
112+
113+
Configuration values are to be retrieved using one of the return typed method from the list:
114+
115+
* ``getValueString(string $app, string $key, string $default, bool $lazy)``
116+
* ``getValueInt(string $app, string $key, int $default, bool $lazy)``
117+
* ``getValueFloat(string $app, string $key, float $default, bool $lazy)``
118+
* ``getValueBool(string $app, string $key, bool $default, bool $lazy)``
119+
* ``getValueArray(string $app, string $key, array $default, bool $lazy)``
120+
121+
122+
Managing config keys
123+
^^^^^^^^^^^^^^^^^^^^
124+
125+
* ``getApps()`` returns list of ids of apps with stored configuration values
126+
* ``getKeys(string $app)`` returns list of stored configuration keys for an app by its id
127+
* ``hasKey(string $app, string $key, ?bool $lazy)`` returns TRUE if key can be found
128+
* ``isSensitive(string $app, string $key, ?bool $lazy)`` returns TRUE if value is set as `sensitive`
129+
* ``isLazy(string $app, string $key)`` returns TRUE if value is set as `lazy`
130+
* ``updateSensitive(string $app, string $key, bool $sensitive)`` update `sensitive` status of a configuration value
131+
* ``updateLazy(string $app, string $key, bool $lazy)`` update `lazy` status of a configuration value
132+
* ``getValueType(string $app, string $key)`` returns bitflag defining the type of a configuration value
133+
* ``deleteKey(string $app, string $key)`` delete a config key and its value
134+
* ``deleteApp(string $app)`` delete all config keys from an app (using app id)
135+
136+
.. note::
137+
Some method allows ``$lazy`` to be ``null``, meaning that the search will be extended to all configuration values, `lazy` or not.
138+
139+
Miscellaneous
140+
^^^^^^^^^^^^^
141+
142+
API also provide extra tools for broaded uses
143+
144+
* ``getAllValues(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
145+
* ``searchValues(string $key, bool $lazy)`` search for apps and values that have a stored value for the specified configuration key.
146+
* ``getDetails(string $app, string $key)`` get all details about a configuration key.
147+
* ``convertTypeToInt(string $type)`` convert human readable string to the bitflag defining the type of a value
148+
* ``convertTypeToString(int $type)`` convert bitflag defining the type of a value to human readable string
149+
* ``clearCache(bool $reload)`` clear internal cache
150+
151+
152+

‎developer_manual/digging_deeper/config/index.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
====================
2+
Config & Preferences
3+
====================
4+
5+
.. toctree::
6+
:maxdepth: 2
7+
8+
appconfig

‎developer_manual/digging_deeper/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Digging deeper
77

88
api
99
changelog
10+
config/index
1011
debugging
1112
classloader
1213
continuous_integration

0 commit comments

Comments
 (0)