mirror of
https://github.com/nextcloud/server.git
synced 2024-12-29 16:38:28 +00:00
325 lines
12 KiB
PHP
325 lines
12 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
/**
|
|
* SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors
|
|
* SPDX-License-Identifier: AGPL-3.0-or-later
|
|
*/
|
|
namespace OCP\AppFramework\Services;
|
|
|
|
use OCP\Exceptions\AppConfigUnknownKeyException;
|
|
|
|
/**
|
|
* Wrapper for AppConfig for the AppFramework
|
|
*
|
|
* @since 20.0.0
|
|
*/
|
|
interface IAppConfig {
|
|
/**
|
|
* Get all keys stored for this app
|
|
*
|
|
* @return string[] the keys stored for the app
|
|
* @since 20.0.0
|
|
*/
|
|
public function getAppKeys(): array;
|
|
|
|
/**
|
|
* Check if a key exists in the list of stored config values.
|
|
*
|
|
* @param string $key config key
|
|
* @param bool $lazy search within lazy loaded config
|
|
*
|
|
* @return bool TRUE if key exists
|
|
* @since 29.0.0
|
|
*/
|
|
public function hasAppKey(string $key, ?bool $lazy = false): bool;
|
|
|
|
/**
|
|
* best way to see if a value is set as sensitive (not displayed in report)
|
|
*
|
|
* @param string $key config key
|
|
* @param bool|null $lazy search within lazy loaded config
|
|
*
|
|
* @return bool TRUE if value is sensitive
|
|
* @throws AppConfigUnknownKeyException if config key is not known
|
|
* @since 29.0.0
|
|
*/
|
|
public function isSensitive(string $key, ?bool $lazy = false): bool;
|
|
|
|
/**
|
|
* Returns if the config key stored in database is lazy loaded
|
|
*
|
|
* **WARNING:** ignore lazy filtering, all config values are loaded from database
|
|
*
|
|
* @param string $key config key
|
|
*
|
|
* @return bool TRUE if config is lazy loaded
|
|
* @throws AppConfigUnknownKeyException if config key is not known
|
|
* @see IAppConfig for details about lazy loading
|
|
* @since 29.0.0
|
|
*/
|
|
public function isLazy(string $key): bool;
|
|
|
|
/**
|
|
* List all config values from an app with config key starting with $key.
|
|
* Returns an array with config key as key, stored value as value.
|
|
*
|
|
* **WARNING:** ignore lazy filtering, all config values are loaded from database
|
|
*
|
|
* @param string $key config keys prefix to search, can be empty.
|
|
* @param bool $filtered filter sensitive config values
|
|
*
|
|
* @return array<string, string|int|float|bool|array> [configKey => configValue]
|
|
* @since 29.0.0
|
|
*/
|
|
public function getAllAppValues(string $key = '', bool $filtered = false): array;
|
|
|
|
/**
|
|
* Writes a new app wide value
|
|
*
|
|
* @param string $key the key of the value, under which will be saved
|
|
* @param string $value the value that should be stored
|
|
* @return void
|
|
* @since 20.0.0
|
|
* @deprecated 29.0.0 use {@see setAppValueString()}
|
|
*/
|
|
public function setAppValue(string $key, string $value): void;
|
|
|
|
/**
|
|
* Store a config key and its value in database
|
|
*
|
|
* If config key is already known with the exact same config value, the database is not updated.
|
|
* If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
|
|
*
|
|
* If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
|
|
*
|
|
* @param string $key config key
|
|
* @param string $value config value
|
|
* @param bool $sensitive if TRUE value will be hidden when listing config values.
|
|
* @param bool $lazy set config as lazy loaded
|
|
*
|
|
* @return bool TRUE if value was different, therefor updated in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function setAppValueString(string $key, string $value, bool $lazy = false, bool $sensitive = false): bool;
|
|
|
|
/**
|
|
* Store a config key and its value in database
|
|
*
|
|
* When handling huge value around and/or above 2,147,483,647, a debug log will be generated
|
|
* on 64bits system, as php int type reach its limit (and throw an exception) on 32bits when using huge numbers.
|
|
*
|
|
* When using huge numbers, it is advised to use {@see \OCP\Util::numericToNumber()} and {@see setValueString()}
|
|
*
|
|
* If config key is already known with the exact same config value, the database is not updated.
|
|
* If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
|
|
*
|
|
* If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
|
|
*
|
|
* @param string $key config key
|
|
* @param int $value config value
|
|
* @param bool $sensitive if TRUE value will be hidden when listing config values.
|
|
* @param bool $lazy set config as lazy loaded
|
|
*
|
|
* @return bool TRUE if value was different, therefor updated in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function setAppValueInt(string $key, int $value, bool $lazy = false, bool $sensitive = false): bool;
|
|
|
|
/**
|
|
* Store a config key and its value in database.
|
|
*
|
|
* If config key is already known with the exact same config value, the database is not updated.
|
|
* If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
|
|
*
|
|
* If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
|
|
*
|
|
* @param string $key config key
|
|
* @param float $value config value
|
|
* @param bool $sensitive if TRUE value will be hidden when listing config values.
|
|
* @param bool $lazy set config as lazy loaded
|
|
*
|
|
* @return bool TRUE if value was different, therefor updated in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function setAppValueFloat(string $key, float $value, bool $lazy = false, bool $sensitive = false): bool;
|
|
|
|
/**
|
|
* Store a config key and its value in database
|
|
*
|
|
* If config key is already known with the exact same config value, the database is not updated.
|
|
* If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
|
|
*
|
|
* If config value was previously stored as lazy loaded, status cannot be altered without using {@see deleteKey()} first
|
|
*
|
|
* @param string $key config key
|
|
* @param bool $value config value
|
|
* @param bool $lazy set config as lazy loaded
|
|
*
|
|
* @return bool TRUE if value was different, therefor updated in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function setAppValueBool(string $key, bool $value, bool $lazy = false): bool;
|
|
|
|
/**
|
|
* Store a config key and its value in database
|
|
*
|
|
* If config key is already known with the exact same config value, the database is not updated.
|
|
* If config key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded.
|
|
*
|
|
* If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first
|
|
*
|
|
* @param string $key config key
|
|
* @param array $value config value
|
|
* @param bool $sensitive if TRUE value will be hidden when listing config values.
|
|
* @param bool $lazy set config as lazy loaded
|
|
*
|
|
* @return bool TRUE if value was different, therefor updated in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function setAppValueArray(string $key, array $value, bool $lazy = false, bool $sensitive = false): bool;
|
|
|
|
/**
|
|
* Looks up an app wide defined value
|
|
*
|
|
* @param string $key the key of the value, under which it was saved
|
|
* @param string $default the default value to be returned if the value isn't set
|
|
*
|
|
* @return string the saved value
|
|
* @since 20.0.0
|
|
* @deprecated 29.0.0 use {@see getAppValueString()}
|
|
*/
|
|
public function getAppValue(string $key, string $default = ''): string;
|
|
|
|
/**
|
|
* Get config value assigned to a config key.
|
|
* If config key is not found in database, default value is returned.
|
|
* If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
|
|
*
|
|
* @param string $key config key
|
|
* @param string $default default value
|
|
* @param bool $lazy search within lazy loaded config
|
|
*
|
|
* @return string stored config value or $default if not set in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function getAppValueString(string $key, string $default = '', bool $lazy = false): string;
|
|
|
|
/**
|
|
* Get config value assigned to a config key.
|
|
* If config key is not found in database, default value is returned.
|
|
* If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
|
|
*
|
|
* @param string $key config key
|
|
* @param int $default default value
|
|
* @param bool $lazy search within lazy loaded config
|
|
*
|
|
* @return int stored config value or $default if not set in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function getAppValueInt(string $key, int $default = 0, bool $lazy = false): int;
|
|
|
|
/**
|
|
* Get config value assigned to a config key.
|
|
* If config key is not found in database, default value is returned.
|
|
* If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
|
|
*
|
|
* @param string $key config key
|
|
* @param float $default default value
|
|
* @param bool $lazy search within lazy loaded config
|
|
*
|
|
* @return float stored config value or $default if not set in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function getAppValueFloat(string $key, float $default = 0, bool $lazy = false): float;
|
|
|
|
/**
|
|
* Get config value assigned to a config key.
|
|
* If config key is not found in database, default value is returned.
|
|
* If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
|
|
*
|
|
* @param string $key config key
|
|
* @param bool $default default value
|
|
* @param bool $lazy search within lazy loaded config
|
|
*
|
|
* @return bool stored config value or $default if not set in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function getAppValueBool(string $key, bool $default = false, bool $lazy = false): bool;
|
|
|
|
/**
|
|
* Get config value assigned to a config key.
|
|
* If config key is not found in database, default value is returned.
|
|
* If config key is set as lazy loaded, the $lazy argument needs to be set to TRUE.
|
|
*
|
|
* @param string $key config key
|
|
* @param array $default default value
|
|
* @param bool $lazy search within lazy loaded config
|
|
*
|
|
* @return array stored config value or $default if not set in database
|
|
* @since 29.0.0
|
|
* @see \OCP\IAppConfig for explanation about lazy loading
|
|
*/
|
|
public function getAppValueArray(string $key, array $default = [], bool $lazy = false): array;
|
|
|
|
/**
|
|
* Delete an app wide defined value
|
|
*
|
|
* @param string $key the key of the value, under which it was saved
|
|
* @return void
|
|
* @since 20.0.0
|
|
*/
|
|
public function deleteAppValue(string $key): void;
|
|
|
|
/**
|
|
* Removes all keys in appconfig belonging to the app
|
|
*
|
|
* @return void
|
|
* @since 20.0.0
|
|
*/
|
|
public function deleteAppValues(): void;
|
|
|
|
/**
|
|
* Set a user defined value
|
|
*
|
|
* @param string $userId the userId of the user that we want to store the value under
|
|
* @param string $key the key under which the value is being stored
|
|
* @param string $value the value that you want to store
|
|
* @param string $preCondition only update if the config value was previously the value passed as $preCondition
|
|
* @throws \OCP\PreConditionNotMetException if a precondition is specified and is not met
|
|
* @throws \UnexpectedValueException when trying to store an unexpected value
|
|
* @since 20.0.0
|
|
*/
|
|
public function setUserValue(string $userId, string $key, string $value, ?string $preCondition = null): void;
|
|
|
|
/**
|
|
* Shortcut for getting a user defined value
|
|
*
|
|
* @param string $userId the userId of the user that we want to store the value under
|
|
* @param string $key the key under which the value is being stored
|
|
* @param mixed $default the default value to be returned if the value isn't set
|
|
* @return string
|
|
* @since 20.0.0
|
|
*/
|
|
public function getUserValue(string $userId, string $key, string $default = ''): string;
|
|
|
|
/**
|
|
* Delete a user value
|
|
*
|
|
* @param string $userId the userId of the user that we want to store the value under
|
|
* @param string $key the key under which the value is being stored
|
|
* @since 20.0.0
|
|
*/
|
|
public function deleteUserValue(string $userId, string $key): void;
|
|
}
|