Skip to content

Commit 34e065f

Browse files
ArtificialOwlArtificialOwl
committed
Config Lexicon
Signed-off-by: Maxence Lange <maxence@artificial-owl.com>
1 parent 4dcf876 commit 34e065f

File tree

4 files changed

+166
-0
lines changed

4 files changed

+166
-0
lines changed

‎developer_manual/digging_deeper/config/appconfig.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,14 @@ On top of storing and accessing your configuration values, ``IAppConfig`` comes
4040

4141
.. _appconfig_concepts:
4242

43+
44+
.. note::
45+
See `Lexicon Concepts`_ to learn more about **Lexicon**, a way to fully define your configuration keys and avoid conflict when using it in your code.
46+
47+
.. _Lexicon Concepts: https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/config/lexicon.html#concept-overview
48+
49+
50+
4351
Typed Config Values
4452
^^^^^^^^^^^^^^^^^^^
4553

‎developer_manual/digging_deeper/config/index.rst

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

88
appconfig
99
userconfig
10+
lexicon

‎developer_manual/digging_deeper/config/lexicon.rst

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
=======
2+
Lexicon
3+
=======
4+
5+
.. versionadded:: 32
6+
7+
Since v32, Nextcloud provides a way to centralize the definition of your app's configuration keys and values in a single place.
8+
9+
10+
Concept overview
11+
----------------
12+
13+
Nextcloud includes the ``ILexicon`` API to create a **Lexicon** of your config keys.
14+
This lexicon allow developers to define the config keys of their apps, their value type and additional details.
15+
16+
.. _lexicon_concepts:
17+
18+
Enforcing a unique configuration for each of your config keys in a single location help avoid their misuse.
19+
20+
Details about each config key are:
21+
- config value expected type,
22+
- a default value,
23+
- a description of its use,
24+
- lazy loading setting,
25+
- flags the config key as sensitive or indexable
26+
27+
28+
Registering your Lexicon
29+
^^^^^^^^^^^^^^^^^^^^^^^^
30+
31+
The Lexicon is set in a local class that implements `\OCP\Config\Lexicon\ILexicon` and registered from your ``Application.php``:
32+
33+
.. code-block:: php
34+
35+
public function register(IRegistrationContext $context): void {
36+
$context->registerConfigLexicon(\OCA\MyApp\ConfigLexicon::class);
37+
}
38+
39+
Example of the registered ``ConfigLexicon.php``:
40+
41+
.. code-block:: php
42+
43+
use OCP\Config\Lexicon\Entry;
44+
use OCP\Config\Lexicon\ILexicon;
45+
use OCP\Config\Lexicon\Strictness;
46+
use OCP\Config\ValueType;
47+
48+
class Lexicon implements ILexicon {
49+
public function getStrictness(): Strictness {
50+
return Strictness::WARNING;
51+
}
52+
53+
public function getAppConfigs(): array {
54+
return [
55+
new Entry('key1', ValueType::STRING, 'abcde', 'test key', true, IAppConfig::FLAG_SENSITIVE),
56+
new Entry('key2', ValueType::INT, 12345, 'test key', false)
57+
];
58+
}
59+
60+
public function getUserConfigs(): array {
61+
return [
62+
new Entry('key1', ValueType::STRING, 'abcde', 'test key', true, IUserConfig::FLAG_SENSITIVE),
63+
new Entry('key2', ValueType::INT, 12345, 'test key', false)
64+
];
65+
}
66+
}
67+
68+
69+
Each method ``getUserConfigs()`` and ``getAppConfigs()`` returns a list of ``\OCP\Config\Lexicon\Entry``.
70+
71+
``getStrictness()`` is used to define the expected behavior of the process when reaching a config keys that is not listed in your app's Config Lexicon.
72+
Must returns a value from enum ``\OCP\Config\Lexicon\Strictness``.
73+
74+
Available values:
75+
* ``::IGNORE`` - does not limit the set/get on an unknown config key.
76+
* ``::NOTICE`` - does not limit the set/get on an unknown config key, but generate a notice in the logs.
77+
* ``::WARNING`` - unknown config key will not be set, and get will returns the default value. A warning will be issued in the logs.
78+
* ``::EXCEPTION`` - set/get on an unknown config key will generate an exception.
79+
80+
81+
Config Lexicon Entry
82+
^^^^^^^^^^^^^^^^^^^^
83+
84+
Each config key is defined in a object through those arguments:
85+
86+
.. code-block:: php
87+
88+
new Entry(
89+
key: 'my_config_key', // config key
90+
type: ValueType::STRING, // expected value type when the code set/get value
91+
defaultRaw: 'default value', // value to returns if a config value is not available in the database
92+
definition: 'this is a description of the use for this config key',
93+
lazy: true, // config value is stored as lazy
94+
flags: FLAG_SENSITIVE, // value is sensitive and/or indexable, using IAppConfig::FLAG_*, IUserConfig::FLAG_*
95+
deprecated: false, // if set to ``true`` will generate a notice entry in the nextcloud logs when called
96+
);
97+
98+
.. note:: Unless if set to ``null``, the default value set in the config lexicon overwrite the default value used as argument when calling ``getValueString('my_config_key', 'another default value');``
99+
100+
Preset
101+
^^^^^^
102+
103+
With 32, Nextcloud comes with a list of `preset` to ease the default user experience, based on the context of the instance.
104+
The selection of a preset is optional and can be done right after the setup of Nextcloud, and any time in the future using this occ command:
105+
106+
.. code-block:: bash
107+
108+
$ ./occ config:preset
109+
current preset: NONE
110+
$ ./occ config:preset PRIVATE
111+
current preset: PRIVATE
112+
113+
If you want your app to have a different default value based on the selected Preset, you need to generate a Closure as ``$defaultRaw`` when generating the Lexicon Entry.
114+
The first parameter of the Closure is an Enum ``'\OCP\Config\Lexicon\Preset'`` that define the current Preset:
115+
116+
.. code-block:: php
117+
118+
new Entry('key3', ValueType::STRING, fn (Preset $p): string => match ($p) {
119+
Preset::FAMILY => 'family',
120+
Preset::CLUB, Preset::MEDIUM => 'club+medium',
121+
default => 'none',
122+
}),
123+
124+
Available values:
125+
* ``::LARGE`` - Large size organisation (> 50k accounts)
126+
* ``::MEDIUM`` - Medium size organisation (> 100 accounts)
127+
* ``::SMALL`` - Small size organisation (< 100 accounts)
128+
* ``::SHARED`` - Shared hosting
129+
* ``::EDUCATION`` - School/University
130+
* ``::CLUB`` - Club/Association
131+
* ``::FAMILY`` - Family
132+
* ``::PRIVATE`` - Private
133+
134+
135+
136+
./occ config:app:get --details
137+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
138+
139+
Details from the Lexicon can be extracted using the ``occ`` command
140+
141+
.. code-block:: base
142+
143+
$ ./occ config:app:get myapp my_config_key --details
144+
- app: myapp
145+
- key: my_config_key
146+
- value: 'a_value'
147+
- type: string
148+
- lazy: true
149+
- description:
150+
- sensitive: false
151+

‎developer_manual/digging_deeper/config/userconfig.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@ On top of storing and accessing your configuration values, ``IUserConfig`` comes
1515

1616
.. _userconfig_concepts:
1717

18+
.. note::
19+
See `Lexicon Concepts`_ to learn more about **Lexicon**, a way to fully define your configuration keys and avoid conflict when using it in your code.
20+
21+
.. _Lexicon Concepts: https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/config/lexicon.html#concept-overview
22+
23+
1824
Typed Config Values
1925
^^^^^^^^^^^^^^^^^^^
2026

0 commit comments

Comments
 (0)