From 826d902dd68428f83a14cf422dd27ff99585d1b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Molakvo=C3=A6=20=28skjnldsv=29?= Date: Wed, 20 May 2026 09:56:03 +0200 Subject: [PATCH 1/2] docs(config): replace deprecated IConfig app/user value examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces IConfig::getAppValue/setAppValue with OCP\AppFramework\Services\IAppConfig (deprecated since NC29) and IConfig::getUserValue/setUserValue with OCP\Config\IUserConfig (deprecated since NC31). System values section unchanged — IConfig is still correct there. Fixes #12221 Signed-off-by: John Molakvoæ (skjnldsv) --- .../basics/storage/configuration.rst | 128 +++++++++--------- 1 file changed, 61 insertions(+), 67 deletions(-) diff --git a/developer_manual/basics/storage/configuration.rst b/developer_manual/basics/storage/configuration.rst index d3e9e55834e..abe33425735 100644 --- a/developer_manual/basics/storage/configuration.rst +++ b/developer_manual/basics/storage/configuration.rst @@ -4,42 +4,17 @@ Configuration .. sectionauthor:: Bernhard Posselt -The config that allows the app to set global, app and user settings can be injected from the ServerContainer. All values are saved as strings and must be cast to the correct value. +Nextcloud provides three configuration scopes: system-wide values (``config.php``), +per-app values, and per-user values. Each scope has a dedicated API. -.. code-block:: php - - getContainer(); - - /** - * Controllers - */ - $container->registerService('AuthorService', function(IServerContainer $c): AuthorService { - return new AuthorService( - $c->get(IConfig::class), - $c->get('appName') - ); - }); - } - } - System values ------------- -System values are saved in the :file:`config/config.php` and allow the app to modify and read the global configuration. Please note that ``setSystemValue`` might throw a ``OCP\HintException`` when the config file is read-only. +System values are saved in :file:`config/config.php`. Inject ``\OCP\IConfig`` +and use the ``getSystemValue*`` / ``setSystemValue`` methods. + +Note that ``setSystemValue`` may throw ``OCP\HintException`` when the config file is read-only. .. code-block:: php @@ -50,19 +25,15 @@ System values are saved in the :file:`config/config.php` and allow the app to mo use OCP\IConfig; class AuthorService { - private IConfig $config; - private string $appName; + public function __construct( + private IConfig $config, + ) {} - public function __construct(IConfig $config, string $appName){ - $this->config = $config; - $this->appName = $appName; - } - - public function getSystemValue(string $key) { + public function getSystemValue(string $key): mixed { return $this->config->getSystemValue($key); } - public function setSystemValue(string $key, $value): void { + public function setSystemValue(string $key, mixed $value): void { try { $this->config->setSystemValue($key, $value); } catch (HintException $e) { @@ -71,7 +42,10 @@ System values are saved in the :file:`config/config.php` and allow the app to mo } } -.. note:: It's also possible to use ``getSystemValueBool``, ``getSystemValueString``, ``getSystemValueInt`` to get type hinted return values. +.. note:: + + Use ``getSystemValueBool()``, ``getSystemValueString()``, and ``getSystemValueInt()`` + for typed return values. Naming conventions ~~~~~~~~~~~~~~~~~~ @@ -89,62 +63,82 @@ Here are some examples: 4. ``mail_smtpname`` 5. ``session_lifetime`` + App values ---------- -App values are saved in the database per app and are useful for setting global app settings: +.. versionchanged:: 29 + + Use ``\OCP\AppFramework\Services\IAppConfig`` (app-scoped) or ``\OCP\IAppConfig`` + (global) instead of ``IConfig::getAppValue()`` / ``IConfig::setAppValue()``, + which are deprecated. + +App values are stored in the database and are useful for global app settings. + +Inside an AppFramework app, inject ``\OCP\AppFramework\Services\IAppConfig``. +Methods are automatically scoped to your app — no app ID argument needed. .. code-block:: php config = $config; - $this->appName = $appName; + public function getRetryCount(): int { + return $this->appConfig->getAppValueInt('retry_count', 3); } - public function getAppValue(string $key): string { - return $this->config->getAppValue($this->appName, $key); - } - - public function setAppValue(string $key, string $value): void { - $this->config->setAppValue($this->appName, $key, $value); + public function setRetryCount(int $count): void { + $this->appConfig->setAppValueInt('retry_count', $count); } } +Use ``\OCP\IAppConfig`` when you need to read or write configuration for an +arbitrary app ID (e.g. from a different app's config). + +For a full reference — typed values, lazy loading, sensitive values, key management — +see :doc:`/developer_manual/digging_deeper/config/appconfig`. + + User values ----------- -User values are saved in the database per user and app and are good for saving user specific app settings: +.. versionchanged:: 31 + + Use ``\OCP\Config\IUserConfig`` instead of ``IConfig::getUserValue()`` / + ``IConfig::setUserValue()``, which are deprecated. + +User values are stored in the database per user and app and are suitable for +per-user app settings. + +Inject ``\OCP\Config\IUserConfig`` and use the typed getter/setter methods: .. code-block:: php config = $config; - $this->appName = $appName; - } + public function __construct( + private IUserConfig $userConfig, + ) {} - public function getUserValue(string $key, string $userId): string { - return $this->config->getUserValue($userId, $this->appName, $key); + public function getUserTheme(string $userId): string { + return $this->userConfig->getValueString($userId, 'myapp', 'theme', 'default'); } - public function setUserValue(string $key, string $userId, string $value): void { - $this->config->setUserValue($userId, $this->appName, $key, $value); + public function setUserTheme(string $userId, string $theme): void { + $this->userConfig->setValueString($userId, 'myapp', 'theme', $theme); } } + +For a full reference — typed values, lazy loading, sensitive and indexed values, +key management — see :doc:`/developer_manual/digging_deeper/config/userconfig`. From 606790f4c17ef31798d1b579acc16441ea779d6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Molakvo=C3=A6=20=28skjnldsv=29?= Date: Wed, 20 May 2026 10:39:47 +0200 Subject: [PATCH 2/2] fix(config): fix broken doc cross-references in storage/configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove duplicate /developer_manual/ prefix from :doc: paths — Sphinx source root for the developer manual is developer_manual/ itself, so the absolute paths must start with /digging_deeper/, not /developer_manual/digging_deeper/. Fixes CI warnings: WARNING: unknown document: '/developer_manual/digging_deeper/config/appconfig' WARNING: unknown document: '/developer_manual/digging_deeper/config/userconfig' Signed-off-by: John Molakvoæ (skjnldsv) --- developer_manual/basics/storage/configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer_manual/basics/storage/configuration.rst b/developer_manual/basics/storage/configuration.rst index abe33425735..7233f59327f 100644 --- a/developer_manual/basics/storage/configuration.rst +++ b/developer_manual/basics/storage/configuration.rst @@ -103,7 +103,7 @@ Use ``\OCP\IAppConfig`` when you need to read or write configuration for an arbitrary app ID (e.g. from a different app's config). For a full reference — typed values, lazy loading, sensitive values, key management — -see :doc:`/developer_manual/digging_deeper/config/appconfig`. +see :doc:`/digging_deeper/config/appconfig`. User values @@ -141,4 +141,4 @@ Inject ``\OCP\Config\IUserConfig`` and use the typed getter/setter methods: } For a full reference — typed values, lazy loading, sensitive and indexed values, -key management — see :doc:`/developer_manual/digging_deeper/config/userconfig`. +key management — see :doc:`/digging_deeper/config/userconfig`.