Nextcloud PHP API (master)

IAppConfig
in

Application

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.

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|int|float|bool|array<string|int, mixed>>: List all config values from an app with config key starting with $key.
getApps() : array<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<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

VALUE_ARRAY


    public
        mixed
    VALUE_ARRAY
    = 64

VALUE_BOOL


    public
        mixed
    VALUE_BOOL
    = 32

VALUE_FLOAT


    public
        mixed
    VALUE_FLOAT
    = 16

VALUE_INT


    public
        mixed
    VALUE_INT
    = 8

VALUE_MIXED


    public
        mixed
    VALUE_MIXED
    = 2

VALUE_SENSITIVE


    public
        mixed
    VALUE_SENSITIVE
    = 1

VALUE_STRING


    public
        mixed
    VALUE_STRING
    = 4

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

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

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

Return values

string

deleteApp()

delete all config keys linked to an app


    public
                    deleteApp(string $app) : void

Parameters

$app : string: id of the app

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

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|int|float|bool|array<string|int, mixed>>

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

Return values

[configKey => configValue]

getApps()

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


    public
                    getApps() : array<int, string>

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

Return values

array<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

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>

Use getAllValues() or searchValues()

Parameters

$app : string

Return values

array<string|int, mixed>

getKeys()

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


    public
                    getKeys(string $app) : array<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

Return values

array<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

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

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

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

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

Use getAllValues() or searchValues()

Parameters

$app : string|false
$key : string|false

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

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[, bool|null $lazy = null ]) : int

WARNING: ignore lazy filtering, all config values are loaded from database unless lazy is set to false

Parameters

$app : string: id of the app
$key : string: config key
$lazy : bool|null = null

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

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

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

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 ][, int|null $typedAs = null ]) : 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
$typedAs : int|null = null: enforce type for the returned values self::VALUE_STRING and others

Return values

[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.

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 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

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 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.

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 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.

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 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.

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

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

Return values

bool —

TRUE if database update were necessary

IAppConfig in Application

What is lazy loading ?

Tags

Table of Contents

Constants

Methods

Constants

VALUE_ARRAY

Tags

VALUE_BOOL

Tags

VALUE_FLOAT

Tags

VALUE_INT

Tags

VALUE_MIXED

Tags

VALUE_SENSITIVE

Tags

VALUE_STRING

Tags

Methods

clearCache()

Parameters

Tags

convertTypeToInt()

Parameters

Tags

Return values

convertTypeToString()

Parameters

Tags

Return values

deleteApp()

Parameters

Tags

deleteKey()

Parameters

Tags

getAllValues()

Parameters

Tags

Return values

getApps()

Tags

Return values

getDetails()

Parameters

Tags

Return values

getFilteredValues()

Parameters

Tags

Return values

getKeys()

Parameters

Tags

Return values

getValueArray()

Parameters

Tags

Return values

getValueBool()

Parameters

Tags

Return values

getValueFloat()

Parameters

Tags

Return values

getValueInt()

Parameters

Tags

Return values

getValues()

Parameters

Tags

Return values

getValueString()

Parameters

IAppConfig
in

Application