Nextcloud PHP API (master)

IAppConfig

This class provides an easy way for apps to store config values in the database.

Note: since 29.0.0, it supports lazy loading

What is lazy loading ?

In order to avoid loading useless config values into memory for each request, only non-lazy values are now loaded.

Once a value that is lazy is requested, all lazy values will be loaded.

Similarly, some methods from this class are marked with a warning about ignoring lazy loading. Use them wisely and only on parts of the code that are called during specific requests or actions to avoid loading the lazy values all the time.

Tags
since
7.0.0
since
29.0.0
  • Supporting types and lazy loading

Table of Contents

Constants

VALUE_ARRAY  = 64
VALUE_BOOL  = 32
VALUE_FLOAT  = 16
VALUE_INT  = 8
VALUE_MIXED  = 2
VALUE_SENSITIVE  = 1
VALUE_STRING  = 4

Methods

clearCache()  : void
Clear the cache.
convertTypeToInt()  : int
Convert string like 'string', 'integer', 'float', 'bool' or 'array' to to bitflag {@see VALUE_STRING}, {@see VALUE_INT}, {@see VALUE_FLOAT}, {@see VALUE_BOOL} and {@see VALUE_ARRAY}
convertTypeToString()  : string
Convert bitflag {@see VALUE_STRING}, {@see VALUE_INT}, {@see VALUE_FLOAT}, {@see VALUE_BOOL} and {@see VALUE_ARRAY} to human-readable string
deleteApp()  : void
delete all config keys linked to an app
deleteKey()  : void
Delete single config key from database.
getAllValues()  : array<string, string>
List all config values from an app with config key starting with $key.
getApps()  : array<string|int, string>
Get list of all apps that have at least one config value stored in database
getDetails()  : array<string|int, mixed>
returns an array contains details about a config value
getFilteredValues()  : array<string|int, mixed>
get all values of the app or and filters out sensitive data
getKeys()  : array<string|int, string>
Returns all keys stored in database, related to an app.
getValueArray()  : array<string|int, mixed>
Get config value assigned to a config key.
getValueBool()  : bool
Get config value assigned to a config key.
getValueFloat()  : float
Get config value assigned to a config key.
getValueInt()  : int
Get config value assigned to a config key.
getValues()  : array<string|int, mixed>|false
get multiply values, either the app or key can be used as wildcard by setting it to false
getValueString()  : string
Get config value assigned to a config key.
getValueType()  : int
returns the type of config value
hasKey()  : bool
Check if a key exists in the list of stored config values.
isLazy()  : bool
Returns if the config key stored in database is lazy loaded
isSensitive()  : bool
best way to see if a value is set as sensitive (not displayed in report)
searchValues()  : array<string, string|int|float|bool|array<string|int, mixed>>
List all apps storing a specific config key and its stored value.
setValueArray()  : bool
Store a config key and its value in database
setValueBool()  : bool
Store a config key and its value in database
setValueFloat()  : bool
Store a config key and its value in database.
setValueInt()  : bool
Store a config key and its value in database
setValueString()  : bool
Store a config key and its value in database
updateLazy()  : bool
switch lazy loading status of a config value
updateSensitive()  : bool
switch sensitive status of a config value

Constants

VALUE_ARRAY

public mixed VALUE_ARRAY = 64
Tags
since
29.0.0

VALUE_BOOL

public mixed VALUE_BOOL = 32
Tags
since
29.0.0

VALUE_FLOAT

public mixed VALUE_FLOAT = 16
Tags
since
29.0.0

VALUE_INT

public mixed VALUE_INT = 8
Tags
since
29.0.0

VALUE_MIXED

public mixed VALUE_MIXED = 2
Tags
since
29.0.0

VALUE_SENSITIVE

public mixed VALUE_SENSITIVE = 1
Tags
since
29.0.0

VALUE_STRING

public mixed VALUE_STRING = 4
Tags
since
29.0.0

Methods

clearCache()

Clear the cache.

public clearCache([bool $reload = false ]) : void

The cache will be rebuilt only the next time a config value is requested.

Parameters
$reload : bool = false

set to TRUE to refill cache instantly after clearing it

Tags
since
29.0.0

convertTypeToInt()

Convert string like 'string', 'integer', 'float', 'bool' or 'array' to to bitflag {@see VALUE_STRING}, {@see VALUE_INT}, {@see VALUE_FLOAT}, {@see VALUE_BOOL} and {@see VALUE_ARRAY}

public convertTypeToInt(string $type) : int
Parameters
$type : string
Tags
since
29.0.0
Return values
int

convertTypeToString()

Convert bitflag {@see VALUE_STRING}, {@see VALUE_INT}, {@see VALUE_FLOAT}, {@see VALUE_BOOL} and {@see VALUE_ARRAY} to human-readable string

public convertTypeToString(int $type) : string
Parameters
$type : int
Tags
since
29.0.0
Return values
string

deleteApp()

delete all config keys linked to an app

public deleteApp(string $app) : void
Parameters
$app : string

id of the app

Tags
since
29.0.0

deleteKey()

Delete single config key from database.

public deleteKey(string $app, string $key) : void
Parameters
$app : string

id of the app

$key : string

config key

Tags
since
29.0.0

getAllValues()

List all config values from an app with config key starting with $key.

public getAllValues(string $app[, string $prefix = '' ][, bool $filtered = false ]) : array<string, string>

Returns an array with config key as key, stored value as value.

WARNING: ignore lazy filtering, all config values are loaded from database

Parameters
$app : string

id of the app

$prefix : string = ''

config keys prefix to search, can be empty.

$filtered : bool = false

filter sensitive config values

Tags
since
29.0.0
Return values
array<string, string>

[configKey => configValue]

getApps()

Get list of all apps that have at least one config value stored in database

public getApps() : array<string|int, string>

WARNING: ignore lazy filtering, all config values are loaded from database

Tags
since
7.0.0
Return values
array<string|int, string>

list of app ids

getDetails()

returns an array contains details about a config value

public getDetails(string $app, string $key) : array<string|int, mixed>
[
  "app" => "myapp",
  "key" => "mykey",
  "value" => "its_value",
  "lazy" => false,
  "type" => 4,
  "typeString" => "string",
  'sensitive' => true
]
Parameters
$app : string

id of the app

$key : string

config key

Tags
throws
AppConfigUnknownKeyException

if config key is not known in database

since
29.0.0
Return values
array<string|int, mixed>

getFilteredValues()

get all values of the app or and filters out sensitive data

public getFilteredValues(string $app) : array<string|int, mixed>
Parameters
$app : string
Tags
since
12.0.0
deprecated
29.0.0

Use getAllValues() or searchValues()

Return values
array<string|int, mixed>

getKeys()

Returns all keys stored in database, related to an app.

public getKeys(string $app) : array<string|int, string>

Please note that the values are not returned.

WARNING: ignore lazy filtering, all config values are loaded from database

Parameters
$app : string

id of the app

Tags
since
29.0.0
Return values
array<string|int, string>

list of stored config keys

getValueArray()

Get config value assigned to a config key.

public getValueArray(string $app, string $key[, array<string|int, mixed> $default = [] ][, bool $lazy = false ]) : array<string|int, mixed>

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.

Parameters
$app : string

id of the app

$key : string

config key

$default : array<string|int, mixed> = []

default value

$lazy : bool = false

search within lazy loaded config

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
getValueString()
see
getValueInt()
see
getValueFloat()
see
getValueBool()
Return values
array<string|int, mixed>

stored config value or $default if not set in database

getValueBool()

Get config value assigned to a config key.

public getValueBool(string $app, string $key[, bool $default = false ][, bool $lazy = false ]) : bool

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.

Parameters
$app : string

id of the app

$key : string

config key

$default : bool = false

default value

$lazy : bool = false

search within lazy loaded config

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
getValueString()
see
getValueInt()
see
getValueFloat()
see
getValueArray()
Return values
bool

stored config value or $default if not set in database

getValueFloat()

Get config value assigned to a config key.

public getValueFloat(string $app, string $key[, float $default = 0 ][, bool $lazy = false ]) : float

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.

Parameters
$app : string

id of the app

$key : string

config key

$default : float = 0

default value

$lazy : bool = false

search within lazy loaded config

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
getValueString()
see
getValueInt()
see
getValueBool()
see
getValueArray()
Return values
float

stored config value or $default if not set in database

getValueInt()

Get config value assigned to a config key.

public getValueInt(string $app, string $key[, int $default = 0 ][, bool $lazy = false ]) : int

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.

Parameters
$app : string

id of the app

$key : string

config key

$default : int = 0

default value

$lazy : bool = false

search within lazy loaded config

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
getValueString()
see
getValueFloat()
see
getValueBool()
see
getValueArray()
Return values
int

stored config value or $default if not set in database

getValues()

get multiply values, either the app or key can be used as wildcard by setting it to false

public getValues(string|false $app, string|false $key) : array<string|int, mixed>|false
Parameters
$app : string|false
$key : string|false
Tags
since
7.0.0
deprecated
29.0.0

Use getAllValues() or searchValues()

Return values
array<string|int, mixed>|false

getValueString()

Get config value assigned to a config key.

public getValueString(string $app, string $key[, string $default = '' ][, bool $lazy = false ]) : string

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.

Parameters
$app : string

id of the app

$key : string

config key

$default : string = ''

default value

$lazy : bool = false

search within lazy loaded config

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
getValueInt()
see
getValueFloat()
see
getValueBool()
see
getValueArray()
Return values
string

stored config value or $default if not set in database

getValueType()

returns the type of config value

public getValueType(string $app, string $key) : int

WARNING: ignore lazy filtering, all config values are loaded from database

Parameters
$app : string

id of the app

$key : string

config key

Tags
throws
AppConfigUnknownKeyException
since
29.0.0
see
VALUE_STRING
see
VALUE_INT
see
VALUE_FLOAT
see
VALUE_BOOL
see
VALUE_ARRAY
Return values
int

hasKey()

Check if a key exists in the list of stored config values.

public hasKey(string $app, string $key[, bool $lazy = false ]) : bool
Parameters
$app : string

id of the app

$key : string

config key

$lazy : bool = false

search within lazy loaded config

Tags
since
29.0.0

Added the $lazy argument

since
7.0.0
Return values
bool

TRUE if key exists

isLazy()

Returns if the config key stored in database is lazy loaded

public isLazy(string $app, string $key) : bool

WARNING: ignore lazy filtering, all config values are loaded from database

Parameters
$app : string

id of the app

$key : string

config key

Tags
throws
AppConfigUnknownKeyException

if config key is not known

see
IAppConfig

for details about lazy loading

since
29.0.0
Return values
bool

TRUE if config is lazy loaded

isSensitive()

best way to see if a value is set as sensitive (not displayed in report)

public isSensitive(string $app, string $key[, bool|null $lazy = false ]) : bool
Parameters
$app : string

id of the app

$key : string

config key

$lazy : bool|null = false

search within lazy loaded config

Tags
throws
AppConfigUnknownKeyException

if config key is not known

since
29.0.0
Return values
bool

TRUE if value is sensitive

searchValues()

List all apps storing a specific config key and its stored value.

public searchValues(string $key[, bool $lazy = false ]) : array<string, string|int|float|bool|array<string|int, mixed>>

Returns an array with appId as key, stored value as value.

Parameters
$key : string

config key

$lazy : bool = false

search within lazy loaded config

Tags
since
29.0.0
Return values
array<string, string|int|float|bool|array<string|int, mixed>>

[appId => configValue]

setValueArray()

Store a config key and its value in database

public setValueArray(string $app, string $key, array<string|int, mixed> $value[, bool $lazy = false ][, bool $sensitive = false ]) : bool

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 deleteKey() first

Parameters
$app : string

id of the app

$key : string

config key

$value : array<string|int, mixed>

config value

$lazy : bool = false

set config as lazy loaded

$sensitive : bool = false

if TRUE value will be hidden when listing config values.

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
setValueString()
see
setValueInt()
see
setValueFloat()
see
setValueBool()
Return values
bool

TRUE if value was different, therefor updated in database

setValueBool()

Store a config key and its value in database

public setValueBool(string $app, string $key, bool $value[, bool $lazy = false ]) : bool

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 deleteKey() first

Parameters
$app : string

id of the app

$key : string

config key

$value : bool

config value

$lazy : bool = false

set config as lazy loaded

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
setValueString()
see
setValueInt()
see
setValueFloat()
see
setValueArray()
Return values
bool

TRUE if value was different, therefor updated in database

setValueFloat()

Store a config key and its value in database.

public setValueFloat(string $app, string $key, float $value[, bool $lazy = false ][, bool $sensitive = false ]) : bool

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 deleteKey() first

Parameters
$app : string

id of the app

$key : string

config key

$value : float

config value

$lazy : bool = false

set config as lazy loaded

$sensitive : bool = false

if TRUE value will be hidden when listing config values.

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
setValueString()
see
setValueInt()
see
setValueBool()
see
setValueArray()
Return values
bool

TRUE if value was different, therefor updated in database

setValueInt()

Store a config key and its value in database

public setValueInt(string $app, string $key, int $value[, bool $lazy = false ][, bool $sensitive = false ]) : bool

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 Util::numericToNumber() and 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 deleteKey() first

Parameters
$app : string

id of the app

$key : string

config key

$value : int

config value

$lazy : bool = false

set config as lazy loaded

$sensitive : bool = false

if TRUE value will be hidden when listing config values.

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
setValueString()
see
setValueFloat()
see
setValueBool()
see
setValueArray()
Return values
bool

TRUE if value was different, therefor updated in database

setValueString()

Store a config key and its value in database

public setValueString(string $app, string $key, string $value[, bool $lazy = false ][, bool $sensitive = false ]) : bool

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 deleteKey() first

Parameters
$app : string

id of the app

$key : string

config key

$value : string

config value

$lazy : bool = false

set config as lazy loaded

$sensitive : bool = false

if TRUE value will be hidden when listing config values.

Tags
since
29.0.0
see
IAppConfig

for explanation about lazy loading

see
setValueInt()
see
setValueFloat()
see
setValueBool()
see
setValueArray()
Return values
bool

TRUE if value was different, therefor updated in database

updateLazy()

switch lazy loading status of a config value

public updateLazy(string $app, string $key, bool $lazy) : bool
Parameters
$app : string

id of the app

$key : string

config key

$lazy : bool

TRUE to set as lazy loaded, FALSE to unset

Tags
since
29.0.0
Return values
bool

TRUE if database update was necessary

updateSensitive()

switch sensitive status of a config value

public updateSensitive(string $app, string $key, bool $sensitive) : bool

WARNING: ignore lazy filtering, all config values are loaded from database

Parameters
$app : string

id of the app

$key : string

config key

$sensitive : bool

TRUE to set as sensitive, FALSE to unset

Tags
since
29.0.0
Return values
bool

TRUE if database update were necessary


        
On this page

Search results