Skip to content

Commit 826d902

Browse files
skjnldsvskjnldsv
committed
docs(config): replace deprecated IConfig app/user value examples
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) <skjnldsv@protonmail.com>
1 parent 00e2e61 commit 826d902

1 file changed

Lines changed: 61 additions & 67 deletions

File tree

‎developer_manual/basics/storage/configuration.rst‎

Lines changed: 61 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -4,42 +4,17 @@ Configuration
44

55
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
66

7-
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.
7+
Nextcloud provides three configuration scopes: system-wide values (``config.php``),
8+
per-app values, and per-user values. Each scope has a dedicated API.
89

910

10-
.. code-block:: php
11-
12-
<?php
13-
namespace OCA\MyApp\AppInfo;
14-
15-
use OCP\AppFramework\App;
16-
use OCP\IConfig;
17-
use OCP\IServerContainer;
18-
use OCA\MyApp\Service\AuthorService;
19-
20-
class Application extends App {
21-
22-
public function __construct(array $urlParams=array()){
23-
parent::__construct('myapp', $urlParams);
24-
25-
$container = $this->getContainer();
26-
27-
/**
28-
* Controllers
29-
*/
30-
$container->registerService('AuthorService', function(IServerContainer $c): AuthorService {
31-
return new AuthorService(
32-
$c->get(IConfig::class),
33-
$c->get('appName')
34-
);
35-
});
36-
}
37-
}
38-
3911
System values
4012
-------------
4113

42-
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.
14+
System values are saved in :file:`config/config.php`. Inject ``\OCP\IConfig``
15+
and use the ``getSystemValue*`` / ``setSystemValue`` methods.
16+
17+
Note that ``setSystemValue`` may throw ``OCP\HintException`` when the config file is read-only.
4318

4419
.. code-block:: php
4520
@@ -50,19 +25,15 @@ System values are saved in the :file:`config/config.php` and allow the app to mo
5025
use OCP\IConfig;
5126
5227
class AuthorService {
53-
private IConfig $config;
54-
private string $appName;
28+
public function __construct(
29+
private IConfig $config,
30+
) {}
5531
56-
public function __construct(IConfig $config, string $appName){
57-
$this->config = $config;
58-
$this->appName = $appName;
59-
}
60-
61-
public function getSystemValue(string $key) {
32+
public function getSystemValue(string $key): mixed {
6233
return $this->config->getSystemValue($key);
6334
}
6435
65-
public function setSystemValue(string $key, $value): void {
36+
public function setSystemValue(string $key, mixed $value): void {
6637
try {
6738
$this->config->setSystemValue($key, $value);
6839
} catch (HintException $e) {
@@ -71,7 +42,10 @@ System values are saved in the :file:`config/config.php` and allow the app to mo
7142
}
7243
}
7344
74-
.. note:: It's also possible to use ``getSystemValueBool``, ``getSystemValueString``, ``getSystemValueInt`` to get type hinted return values.
45+
.. note::
46+
47+
Use ``getSystemValueBool()``, ``getSystemValueString()``, and ``getSystemValueInt()``
48+
for typed return values.
7549

7650
Naming conventions
7751
~~~~~~~~~~~~~~~~~~
@@ -89,62 +63,82 @@ Here are some examples:
8963
4. ``mail_smtpname``
9064
5. ``session_lifetime``
9165

66+
9267
App values
9368
----------
9469

95-
App values are saved in the database per app and are useful for setting global app settings:
70+
.. versionchanged:: 29
71+
72+
Use ``\OCP\AppFramework\Services\IAppConfig`` (app-scoped) or ``\OCP\IAppConfig``
73+
(global) instead of ``IConfig::getAppValue()`` / ``IConfig::setAppValue()``,
74+
which are deprecated.
75+
76+
App values are stored in the database and are useful for global app settings.
77+
78+
Inside an AppFramework app, inject ``\OCP\AppFramework\Services\IAppConfig``.
79+
Methods are automatically scoped to your app — no app ID argument needed.
9680

9781
.. code-block:: php
9882
9983
<?php
10084
namespace OCA\MyApp\Service;
10185
102-
use OCP\IConfig;
86+
use OCP\AppFramework\Services\IAppConfig;
10387
10488
class AuthorService {
105-
private IConfig $config;
106-
private string $appName;
89+
public function __construct(
90+
private IAppConfig $appConfig,
91+
) {}
10792
108-
public function __construct(IConfig $config, string $appName){
109-
$this->config = $config;
110-
$this->appName = $appName;
93+
public function getRetryCount(): int {
94+
return $this->appConfig->getAppValueInt('retry_count', 3);
11195
}
11296
113-
public function getAppValue(string $key): string {
114-
return $this->config->getAppValue($this->appName, $key);
115-
}
116-
117-
public function setAppValue(string $key, string $value): void {
118-
$this->config->setAppValue($this->appName, $key, $value);
97+
public function setRetryCount(int $count): void {
98+
$this->appConfig->setAppValueInt('retry_count', $count);
11999
}
120100
}
121101
102+
Use ``\OCP\IAppConfig`` when you need to read or write configuration for an
103+
arbitrary app ID (e.g. from a different app's config).
104+
105+
For a full reference — typed values, lazy loading, sensitive values, key management —
106+
see :doc:`/developer_manual/digging_deeper/config/appconfig`.
107+
108+
122109
User values
123110
-----------
124111

125-
User values are saved in the database per user and app and are good for saving user specific app settings:
112+
.. versionchanged:: 31
113+
114+
Use ``\OCP\Config\IUserConfig`` instead of ``IConfig::getUserValue()`` /
115+
``IConfig::setUserValue()``, which are deprecated.
116+
117+
User values are stored in the database per user and app and are suitable for
118+
per-user app settings.
119+
120+
Inject ``\OCP\Config\IUserConfig`` and use the typed getter/setter methods:
126121

127122
.. code-block:: php
128123
129124
<?php
130125
namespace OCA\MyApp\Service;
131126
132-
use OCP\IConfig;
127+
use OCP\Config\IUserConfig;
133128
134129
class AuthorService {
135-
private IConfig $config;
136-
private string $appName;
137-
138-
public function __construct(IConfig $config, string $appName){
139-
$this->config = $config;
140-
$this->appName = $appName;
141-
}
130+
public function __construct(
131+
private IUserConfig $userConfig,
132+
) {}
142133
143-
public function getUserValue(string $key, string $userId): string {
144-
return $this->config->getUserValue($userId, $this->appName, $key);
134+
public function getUserTheme(string $userId): string {
135+
return $this->userConfig->getValueString($userId, 'myapp', 'theme', 'default');
145136
}
146137
147-
public function setUserValue(string $key, string $userId, string $value): void {
148-
$this->config->setUserValue($userId, $this->appName, $key, $value);
138+
public function setUserTheme(string $userId, string $theme): void {
139+
$this->userConfig->setValueString($userId, 'myapp', 'theme', $theme);
149140
}
150141
}
142+
143+
For a full reference — typed values, lazy loading, sensitive and indexed values,
144+
key management — see :doc:`/developer_manual/digging_deeper/config/userconfig`.

0 commit comments

Comments
 (0)