From 54ba77cf5a90060df51788196507430e685e89e5 Mon Sep 17 00:00:00 2001
From: Maxence Lange <maxence@artificial-owl.com>
Date: Fri, 11 Apr 2025 10:24:47 -0100
Subject: [PATCH] Config Lexicon
Signed-off-by: Maxence Lange <maxence@artificial-owl.com>
---
.../digging_deeper/config/appconfig.rst | 8 ++
.../digging_deeper/config/index.rst | 1 +
.../digging_deeper/config/lexicon.rst | 120 ++++++++++++++++++
.../digging_deeper/config/userconfig.rst | 6 +
4 files changed, 135 insertions(+)
create mode 100644 developer_manual/digging_deeper/config/lexicon.rst
diff --git a/developer_manual/digging_deeper/config/appconfig.rst b/developer_manual/digging_deeper/config/appconfig.rst
index c32c576703c..03becaa1baa 100644
--- a/developer_manual/digging_deeper/config/appconfig.rst
+++ b/developer_manual/digging_deeper/config/appconfig.rst
@@ -38,6 +38,14 @@ On top of storing and accessing your configuration values, ``IAppConfig`` comes
.. _appconfig_concepts:
+
+.. note::
+ 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.
+
+.. _Lexicon Concepts: https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/config/lexicon.html#concept-overview
+
+
+
Typed Config Values
^^^^^^^^^^^^^^^^^^^
diff --git a/developer_manual/digging_deeper/config/index.rst b/developer_manual/digging_deeper/config/index.rst
index 073df43f6aa..c72ed2908a1 100644
--- a/developer_manual/digging_deeper/config/index.rst
+++ b/developer_manual/digging_deeper/config/index.rst
@@ -7,3 +7,4 @@ Config & Preferences
appconfig
userconfig
+ lexicon
diff --git a/developer_manual/digging_deeper/config/lexicon.rst b/developer_manual/digging_deeper/config/lexicon.rst
new file mode 100644
index 00000000000..bb2e4899ba6
--- /dev/null
+++ b/developer_manual/digging_deeper/config/lexicon.rst
@@ -0,0 +1,120 @@
+=======
+Lexicon
+=======
+
+.. versionadded:: 31
+
+Since v31, Nextcloud provides a way to centralize the definition of your app's configuration keys and values in a single place.
+
+
+Concept overview
+----------------
+
+Nextcloud includes the ``IConfigLexicon`` API to create a **Lexicon** of your config keys.
+This lexicon allow to define all the config keys used by your app, their value type and additional details.
+
+.. _lexicon_concepts:
+
+Enforcing a unique configuration for each of your config keys in a single location help avoid their misuse.
+
+Details about each config key are:
+ - config value expected type,
+ - a default value,
+ - a description of its use,
+ - lazy loading setting,
+ - flags the config key as sensitive or indexable
+
+
+Registering your Lexicon
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Lexicon is set in a local class that implements `IconfigLexicon` and registered from your ``Application.php``:
+
+.. code-block:: php
+
+ public function register(IRegistrationContext $context): void {
+ $context->registerConfigLexicon(\OCA\MyApp\ConfigLexicon::class);
+ }
+
+Example of the registered ``ConfigLexicon.php``:
+
+.. code-block:: php
+
+ class Lexicon implements IConfigLexicon {
+ public function getStrictness(): ConfigLexiconStrictness {
+ return ConfigLexiconStrictness::WARNING;
+ }
+
+ public function getAppConfigs(): array {
+ return [
+ new ConfigLexiconEntry('key1', ValueType::STRING, 'abcde', 'test key', true, IAppConfig::FLAG_SENSITIVE),
+ new ConfigLexiconEntry('key2', ValueType::INT, 12345, 'test key', false)
+ ];
+ }
+
+ public function getUserConfigs(): array {
+ return [
+ new ConfigLexiconEntry('key1', ValueType::STRING, 'abcde', 'test key', true, IUserConfig::FLAG_SENSITIVE),
+ new ConfigLexiconEntry('key2', ValueType::INT, 12345, 'test key', false)
+ ];
+ }
+ }
+
+
+Each method ``getUserConfigs()`` and ``getAppConfigs()`` returns a list of ``ConfigLexiconEntry``.
+
+``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.
+Must returns a value from enum ``\OCP\Config\Lexicon\ConfigLexiconStrictness``.
+
+Available values:
+ * ``::IGNORE`` - does not limit the set/get on an unknown config key.
+ * ``::NOTICE`` - does not limit the set/get on an unknown config key, but generate a notice in the logs.
+ * ``::WARNING`` - unknown config key will not be set, and get will returns the default value. A warning will be issued in the logs.
+ * ``::EXCEPTION`` - set/get on an unknown config key will generate an exception.
+
+
+ConfigLexiconEntry
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: php
+
+ new ``ConfigLexiconEntry``(
+ 'my_config_key',
+ \OCP\Config\ValueType::STRING,
+ 'default value',
+ 'this is a description of the use for this config key',
+ lazy: true,
+ flags: FLAG_SENSITIVE
+ );
+
+Each config key is defined in a object through those arguments:
+
+ * ``key``: config key
+ * ``type``: expected value type when the code set/get the config key's value
+ * ``defaultRaw``: value to returns if a config value is not available in the database
+ * ``description``: textual description of the use made from the config value,
+ * ``lazy``: config value is stored as Lazy
+ * ``flags``: value is sensitive and/or indexable, using ``IAppConfig::FLAG_SENSITIVE``, ``IUserConfig::FLAG_SENSITIVE``, ``IUserConfig::FLAG_INDEXED``,
+ * ``deprecated``: if set to ``true`` will generate a notice entry in the nextcloud logs when called
+
+
+.. 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');``
+
+
+
+./occ config:app:get --details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Details from the Lexicon can be extracted using the ``occ`` command
+
+::
+
+ $ ./occ config:app:get myapp my_config_key --details
+ - app: myapp
+ - key: my_config_key
+ - value: 'a_value'
+ - type: string
+ - lazy: true
+ - description:
+ - sensitive: false
+
diff --git a/developer_manual/digging_deeper/config/userconfig.rst b/developer_manual/digging_deeper/config/userconfig.rst
index 947ef7e508e..b50e66d7bc8 100644
--- a/developer_manual/digging_deeper/config/userconfig.rst
+++ b/developer_manual/digging_deeper/config/userconfig.rst
@@ -15,6 +15,12 @@ On top of storing and accessing your configuration values, ``IUserConfig`` comes
.. _userconfig_concepts:
+.. note::
+ 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.
+
+.. _Lexicon Concepts: https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/config/lexicon.html#concept-overview
+
+
Typed Config Values
^^^^^^^^^^^^^^^^^^^