1
0

IAppConfig.php 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
  6. * SPDX-License-Identifier: AGPL-3.0-only
  7. */
  8. namespace OCP;
  9. use OCP\Exceptions\AppConfigUnknownKeyException;
  10. /**
  11. * This class provides an easy way for apps to store config values in the
  12. * database.
  13. *
  14. * **Note:** since 29.0.0, it supports **lazy loading**
  15. *
  16. * ### What is lazy loading ?
  17. * In order to avoid loading useless config values into memory for each request,
  18. * only non-lazy values are now loaded.
  19. *
  20. * Once a value that is lazy is requested, all lazy values will be loaded.
  21. *
  22. * Similarly, some methods from this class are marked with a warning about ignoring
  23. * lazy loading. Use them wisely and only on parts of the code that are called
  24. * during specific requests or actions to avoid loading the lazy values all the time.
  25. *
  26. * @since 7.0.0
  27. * @since 29.0.0 - Supporting types and lazy loading
  28. */
  29. interface IAppConfig {
  30. /** @since 29.0.0 */
  31. public const VALUE_SENSITIVE = 1;
  32. /** @since 29.0.0 */
  33. public const VALUE_MIXED = 2;
  34. /** @since 29.0.0 */
  35. public const VALUE_STRING = 4;
  36. /** @since 29.0.0 */
  37. public const VALUE_INT = 8;
  38. /** @since 29.0.0 */
  39. public const VALUE_FLOAT = 16;
  40. /** @since 29.0.0 */
  41. public const VALUE_BOOL = 32;
  42. /** @since 29.0.0 */
  43. public const VALUE_ARRAY = 64;
  44. /**
  45. * Get list of all apps that have at least one config value stored in database
  46. *
  47. * **WARNING:** ignore lazy filtering, all config values are loaded from database
  48. *
  49. * @return string[] list of app ids
  50. * @since 7.0.0
  51. */
  52. public function getApps(): array;
  53. /**
  54. * Returns all keys stored in database, related to an app.
  55. * Please note that the values are not returned.
  56. *
  57. * **WARNING:** ignore lazy filtering, all config values are loaded from database
  58. *
  59. * @param string $app id of the app
  60. *
  61. * @return string[] list of stored config keys
  62. * @since 29.0.0
  63. */
  64. public function getKeys(string $app): array;
  65. /**
  66. * Check if a key exists in the list of stored config values.
  67. *
  68. * @param string $app id of the app
  69. * @param string $key config key
  70. * @param bool $lazy search within lazy loaded config
  71. *
  72. * @return bool TRUE if key exists
  73. * @since 29.0.0 Added the $lazy argument
  74. * @since 7.0.0
  75. */
  76. public function hasKey(string $app, string $key, ?bool $lazy = false): bool;
  77. /**
  78. * best way to see if a value is set as sensitive (not displayed in report)
  79. *
  80. * @param string $app id of the app
  81. * @param string $key config key
  82. * @param bool|null $lazy search within lazy loaded config
  83. *
  84. * @return bool TRUE if value is sensitive
  85. * @throws AppConfigUnknownKeyException if config key is not known
  86. * @since 29.0.0
  87. */
  88. public function isSensitive(string $app, string $key, ?bool $lazy = false): bool;
  89. /**
  90. * Returns if the config key stored in database is lazy loaded
  91. *
  92. * **WARNING:** ignore lazy filtering, all config values are loaded from database
  93. *
  94. * @param string $app id of the app
  95. * @param string $key config key
  96. *
  97. * @return bool TRUE if config is lazy loaded
  98. * @throws AppConfigUnknownKeyException if config key is not known
  99. * @see IAppConfig for details about lazy loading
  100. * @since 29.0.0
  101. */
  102. public function isLazy(string $app, string $key): bool;
  103. /**
  104. * List all config values from an app with config key starting with $key.
  105. * Returns an array with config key as key, stored value as value.
  106. *
  107. * **WARNING:** ignore lazy filtering, all config values are loaded from database
  108. *
  109. * @param string $app id of the app
  110. * @param string $prefix config keys prefix to search, can be empty.
  111. * @param bool $filtered filter sensitive config values
  112. *
  113. * @return array<string, string|int|float|bool|array> [configKey => configValue]
  114. * @since 29.0.0
  115. */
  116. public function getAllValues(string $app, string $prefix = '', bool $filtered = false): array;
  117. /**
  118. * List all apps storing a specific config key and its stored value.
  119. * Returns an array with appId as key, stored value as value.
  120. *
  121. * @param string $key config key
  122. * @param bool $lazy search within lazy loaded config
  123. * @param int|null $typedAs enforce type for the returned values {@see self::VALUE_STRING} and others
  124. *
  125. * @return array<string, string|int|float|bool|array> [appId => configValue]
  126. * @since 29.0.0
  127. */
  128. public function searchValues(string $key, bool $lazy = false, ?int $typedAs = null): array;
  129. /**
  130. * Get config value assigned to a config key.
  131. * If config key is not found in database, default value is returned.
  132. * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
  133. *
  134. * @param string $app id of the app
  135. * @param string $key config key
  136. * @param string $default default value
  137. * @param bool $lazy search within lazy loaded config
  138. *
  139. * @return string stored config value or $default if not set in database
  140. * @since 29.0.0
  141. * @see IAppConfig for explanation about lazy loading
  142. * @see getValueInt()
  143. * @see getValueFloat()
  144. * @see getValueBool()
  145. * @see getValueArray()
  146. */
  147. public function getValueString(string $app, string $key, string $default = '', bool $lazy = false): string;
  148. /**
  149. * Get config value assigned to a config key.
  150. * If config key is not found in database, default value is returned.
  151. * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
  152. *
  153. * @param string $app id of the app
  154. * @param string $key config key
  155. * @param int $default default value
  156. * @param bool $lazy search within lazy loaded config
  157. *
  158. * @return int stored config value or $default if not set in database
  159. * @since 29.0.0
  160. * @see IAppConfig for explanation about lazy loading
  161. * @see getValueString()
  162. * @see getValueFloat()
  163. * @see getValueBool()
  164. * @see getValueArray()
  165. */
  166. public function getValueInt(string $app, string $key, int $default = 0, bool $lazy = false): int;
  167. /**
  168. * Get config value assigned to a config key.
  169. * If config key is not found in database, default value is returned.
  170. * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
  171. *
  172. * @param string $app id of the app
  173. * @param string $key config key
  174. * @param float $default default value
  175. * @param bool $lazy search within lazy loaded config
  176. *
  177. * @return float stored config value or $default if not set in database
  178. * @since 29.0.0
  179. * @see IAppConfig for explanation about lazy loading
  180. * @see getValueString()
  181. * @see getValueInt()
  182. * @see getValueBool()
  183. * @see getValueArray()
  184. */
  185. public function getValueFloat(string $app, string $key, float $default = 0, bool $lazy = false): float;
  186. /**
  187. * Get config value assigned to a config key.
  188. * If config key is not found in database, default value is returned.
  189. * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
  190. *
  191. * @param string $app id of the app
  192. * @param string $key config key
  193. * @param bool $default default value
  194. * @param bool $lazy search within lazy loaded config
  195. *
  196. * @return bool stored config value or $default if not set in database
  197. * @since 29.0.0
  198. * @see IAppConfig for explanation about lazy loading
  199. * @see getValueString()
  200. * @see getValueInt()
  201. * @see getValueFloat()
  202. * @see getValueArray()
  203. */
  204. public function getValueBool(string $app, string $key, bool $default = false, bool $lazy = false): bool;
  205. /**
  206. * Get config value assigned to a config key.
  207. * If config key is not found in database, default value is returned.
  208. * If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
  209. *
  210. * @param string $app id of the app
  211. * @param string $key config key
  212. * @param array $default default value
  213. * @param bool $lazy search within lazy loaded config
  214. *
  215. * @return array stored config value or $default if not set in database
  216. * @since 29.0.0
  217. * @see IAppConfig for explanation about lazy loading
  218. * @see getValueString()
  219. * @see getValueInt()
  220. * @see getValueFloat()
  221. * @see getValueBool()
  222. */
  223. public function getValueArray(string $app, string $key, array $default = [], bool $lazy = false): array;
  224. /**
  225. * returns the type of config value
  226. *
  227. * **WARNING:** ignore lazy filtering, all config values are loaded from database
  228. * unless lazy is set to false
  229. *
  230. * @param string $app id of the app
  231. * @param string $key config key
  232. * @param bool|null $lazy
  233. *
  234. * @return int
  235. * @throws AppConfigUnknownKeyException
  236. * @since 29.0.0
  237. * @see VALUE_STRING
  238. * @see VALUE_INT
  239. * @see VALUE_FLOAT
  240. * @see VALUE_BOOL
  241. * @see VALUE_ARRAY
  242. */
  243. public function getValueType(string $app, string $key, ?bool $lazy = null): int;
  244. /**
  245. * Store a config key and its value in database
  246. *
  247. * If config key is already known with the exact same config value, the database is not updated.
  248. * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
  249. *
  250. * If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
  251. *
  252. * @param string $app id of the app
  253. * @param string $key config key
  254. * @param string $value config value
  255. * @param bool $sensitive if TRUE value will be hidden when listing config values.
  256. * @param bool $lazy set config as lazy loaded
  257. *
  258. * @return bool TRUE if value was different, therefor updated in database
  259. * @since 29.0.0
  260. * @see IAppConfig for explanation about lazy loading
  261. * @see setValueInt()
  262. * @see setValueFloat()
  263. * @see setValueBool()
  264. * @see setValueArray()
  265. */
  266. public function setValueString(string $app, string $key, string $value, bool $lazy = false, bool $sensitive = false): bool;
  267. /**
  268. * Store a config key and its value in database
  269. *
  270. * When handling huge value around and/or above 2,147,483,647, a debug log will be generated
  271. * on 64bits system, as php int type reach its limit (and throw an exception) on 32bits when using huge numbers.
  272. *
  273. * When using huge numbers, it is advised to use {@see \OCP\Util::numericToNumber()} and {@see setValueString()}
  274. *
  275. * If config key is already known with the exact same config value, the database is not updated.
  276. * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
  277. *
  278. * If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
  279. *
  280. * @param string $app id of the app
  281. * @param string $key config key
  282. * @param int $value config value
  283. * @param bool $sensitive if TRUE value will be hidden when listing config values.
  284. * @param bool $lazy set config as lazy loaded
  285. *
  286. * @return bool TRUE if value was different, therefor updated in database
  287. * @since 29.0.0
  288. * @see IAppConfig for explanation about lazy loading
  289. * @see setValueString()
  290. * @see setValueFloat()
  291. * @see setValueBool()
  292. * @see setValueArray()
  293. */
  294. public function setValueInt(string $app, string $key, int $value, bool $lazy = false, bool $sensitive = false): bool;
  295. /**
  296. * Store a config key and its value in database.
  297. *
  298. * If config key is already known with the exact same config value, the database is not updated.
  299. * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
  300. *
  301. * If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
  302. *
  303. * @param string $app id of the app
  304. * @param string $key config key
  305. * @param float $value config value
  306. * @param bool $sensitive if TRUE value will be hidden when listing config values.
  307. * @param bool $lazy set config as lazy loaded
  308. *
  309. * @return bool TRUE if value was different, therefor updated in database
  310. * @since 29.0.0
  311. * @see IAppConfig for explanation about lazy loading
  312. * @see setValueString()
  313. * @see setValueInt()
  314. * @see setValueBool()
  315. * @see setValueArray()
  316. */
  317. public function setValueFloat(string $app, string $key, float $value, bool $lazy = false, bool $sensitive = false): bool;
  318. /**
  319. * Store a config key and its value in database
  320. *
  321. * If config key is already known with the exact same config value, the database is not updated.
  322. * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
  323. *
  324. * If config value was previously stored as lazy loaded, status cannot be altered without using {@see deleteKey()} first
  325. *
  326. * @param string $app id of the app
  327. * @param string $key config key
  328. * @param bool $value config value
  329. * @param bool $lazy set config as lazy loaded
  330. *
  331. * @return bool TRUE if value was different, therefor updated in database
  332. * @since 29.0.0
  333. * @see IAppConfig for explanation about lazy loading
  334. * @see setValueString()
  335. * @see setValueInt()
  336. * @see setValueFloat()
  337. * @see setValueArray()
  338. */
  339. public function setValueBool(string $app, string $key, bool $value, bool $lazy = false): bool;
  340. /**
  341. * Store a config key and its value in database
  342. *
  343. * If config key is already known with the exact same config value, the database is not updated.
  344. * If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
  345. *
  346. * If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
  347. *
  348. * @param string $app id of the app
  349. * @param string $key config key
  350. * @param array $value config value
  351. * @param bool $sensitive if TRUE value will be hidden when listing config values.
  352. * @param bool $lazy set config as lazy loaded
  353. *
  354. * @return bool TRUE if value was different, therefor updated in database
  355. * @since 29.0.0
  356. * @see IAppConfig for explanation about lazy loading
  357. * @see setValueString()
  358. * @see setValueInt()
  359. * @see setValueFloat()
  360. * @see setValueBool()
  361. */
  362. public function setValueArray(string $app, string $key, array $value, bool $lazy = false, bool $sensitive = false): bool;
  363. /**
  364. * switch sensitive status of a config value
  365. *
  366. * **WARNING:** ignore lazy filtering, all config values are loaded from database
  367. *
  368. * @param string $app id of the app
  369. * @param string $key config key
  370. * @param bool $sensitive TRUE to set as sensitive, FALSE to unset
  371. *
  372. * @return bool TRUE if database update were necessary
  373. * @since 29.0.0
  374. */
  375. public function updateSensitive(string $app, string $key, bool $sensitive): bool;
  376. /**
  377. * switch lazy loading status of a config value
  378. *
  379. * @param string $app id of the app
  380. * @param string $key config key
  381. * @param bool $lazy TRUE to set as lazy loaded, FALSE to unset
  382. *
  383. * @return bool TRUE if database update was necessary
  384. * @since 29.0.0
  385. */
  386. public function updateLazy(string $app, string $key, bool $lazy): bool;
  387. /**
  388. * returns an array contains details about a config value
  389. *
  390. * ```
  391. * [
  392. * "app" => "myapp",
  393. * "key" => "mykey",
  394. * "value" => "its_value",
  395. * "lazy" => false,
  396. * "type" => 4,
  397. * "typeString" => "string",
  398. * 'sensitive' => true
  399. * ]
  400. * ```
  401. *
  402. * @param string $app id of the app
  403. * @param string $key config key
  404. *
  405. * @return array
  406. * @throws AppConfigUnknownKeyException if config key is not known in database
  407. * @since 29.0.0
  408. */
  409. public function getDetails(string $app, string $key): array;
  410. /**
  411. * Convert string like 'string', 'integer', 'float', 'bool' or 'array' to
  412. * to bitflag {@see VALUE_STRING}, {@see VALUE_INT}, {@see VALUE_FLOAT},
  413. * {@see VALUE_BOOL} and {@see VALUE_ARRAY}
  414. *
  415. * @param string $type
  416. *
  417. * @return int
  418. * @since 29.0.0
  419. */
  420. public function convertTypeToInt(string $type): int;
  421. /**
  422. * Convert bitflag {@see VALUE_STRING}, {@see VALUE_INT}, {@see VALUE_FLOAT},
  423. * {@see VALUE_BOOL} and {@see VALUE_ARRAY} to human-readable string
  424. *
  425. * @param int $type
  426. *
  427. * @return string
  428. * @since 29.0.0
  429. */
  430. public function convertTypeToString(int $type): string;
  431. /**
  432. * Delete single config key from database.
  433. *
  434. * @param string $app id of the app
  435. * @param string $key config key
  436. * @since 29.0.0
  437. */
  438. public function deleteKey(string $app, string $key): void;
  439. /**
  440. * delete all config keys linked to an app
  441. *
  442. * @param string $app id of the app
  443. * @since 29.0.0
  444. */
  445. public function deleteApp(string $app): void;
  446. /**
  447. * Clear the cache.
  448. *
  449. * The cache will be rebuilt only the next time a config value is requested.
  450. *
  451. * @param bool $reload set to TRUE to refill cache instantly after clearing it
  452. * @since 29.0.0
  453. */
  454. public function clearCache(bool $reload = false): void;
  455. /**
  456. * get multiply values, either the app or key can be used as wildcard by setting it to false
  457. *
  458. * @param string|false $key
  459. * @param string|false $app
  460. *
  461. * @return array|false
  462. * @since 7.0.0
  463. * @deprecated 29.0.0 Use {@see getAllValues()} or {@see searchValues()}
  464. */
  465. public function getValues($app, $key);
  466. /**
  467. * get all values of the app or and filters out sensitive data
  468. *
  469. * @param string $app
  470. *
  471. * @return array
  472. * @since 12.0.0
  473. * @deprecated 29.0.0 Use {@see getAllValues()} or {@see searchValues()}
  474. */
  475. public function getFilteredValues($app);
  476. }