Nextcloud PHP API (master)

IUserConfig
in

Application

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

Supports lazy loading

What is lazy loading ?

In order to avoid loading useless user config 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.

#[Consumable]: $since: '32.0.0'

Constants

FLAG_INDEXED = 2
FLAG_SENSITIVE = 1

Methods

clearCache() : void: Clear the cache for a single user
clearCacheAll() : void: Clear the cache for all users.
deleteAllUserConfig() : void: delete all config keys linked to a user
deleteApp() : void: delete all config keys linked to an app
deleteKey() : void: Delete config values from all users linked to a specific config keys
deleteUserConfig() : void: Delete single config key from database.
getAllValues() : array<string, string|int|float|bool|array<string|int, mixed>>: List all config values of a user.
getApps() : array<int, string>: Get list of all apps that have at least one config value related to $userId stored in database
getDetails() : array<string|int, mixed>: returns an array contains details about a config value
getKeys() : array<int, string>: Returns all keys stored in database, related to user+app.
getUserIds() : array<int, string>: Get list of all userIds with config stored in database.
getValueArray() : array<string|int, mixed>: Get config value assigned to a config key.
getValueBool() : bool: Get config value assigned to a config key.
getValueFlags() : int: returns a bitflag related to config value
getValueFloat() : float: Get config value assigned to a config key.
getValueInt() : int: Get config value assigned to a config key.
getValues() : array<string, string|int|float|bool|array<string|int, mixed>>: List all config values from an app with config key starting with $key.
getValuesByApps() : array<string, string|int|float|bool|array<string|int, mixed>>: List all apps storing a specific config key and its stored value.
getValuesByUsers() : array<string, string|int|float|bool|array<string|int, mixed>>: List all users storing a specific config key and its stored value.
getValueString() : string: Get user config assigned to a config key.
getValueType() : ValueType: returns the type of config value
hasKey() : bool: Check if a key exists in the list of stored config values.
isIndexed() : bool: best way to see if a value is set as indexed (so it can be search)
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)
searchUsersByValueBool() : Generator<string|int, string>: List all users storing a specific config key/value pair.
searchUsersByValueInt() : Generator<string|int, string>: List all users storing a specific config key/value pair.
searchUsersByValues() : Generator<string|int, string>: List all users storing a specific config key/value pair.
searchUsersByValueString() : Generator<string|int, string>: List all users storing a specific config key/value pair.
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
updateGlobalIndexed() : void: switch sensitive loading status of a config key for all users
updateGlobalLazy() : void: switch lazy loading status of a config key for all users
updateGlobalSensitive() : void: switch sensitive loading status of a config key for all users
updateIndexed() : bool: switch indexed status of a config value
updateLazy() : bool: switch lazy loading status of a config value
updateSensitive() : bool: switch sensitive status of a config value

FLAG_INDEXED


    public
        mixed
    FLAG_INDEXED
    = 2

FLAG_SENSITIVE


    public
        mixed
    FLAG_SENSITIVE
    = 1

clearCache()

Clear the cache for a single user


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

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

Parameters

$userId : string: id of the user
$reload : bool = false: set to TRUE to refill cache instantly after clearing it

clearCacheAll()

Clear the cache for all users.


    public
                    clearCacheAll() : void

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

deleteAllUserConfig()

delete all config keys linked to a user


    public
                    deleteAllUserConfig(string $userId) : void

Parameters

$userId : string: id of the user

deleteApp()

delete all config keys linked to an app


    public
                    deleteApp(string $app) : void

Parameters

$app : string: id of the app

deleteKey()

Delete config values from all users linked to a specific config keys


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

Parameters

$app : string: id of the app
$key : string: config key

deleteUserConfig()

Delete single config key from database.


    public
                    deleteUserConfig(string $userId, string $app, string $key) : void

Parameters

$userId : string: id of the user
$app : string: id of the app
$key : string: config key

getAllValues()

List all config values of a user.


    public
                    getAllValues(string $userId[, 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

$userId : string: id of the user
$filtered : bool = false: filter sensitive config values

Return values

[key => value]

getApps()

Get list of all apps that have at least one config value related to $userId stored in database


    public
                    getApps(string $userId) : array<int, string>

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

Parameters

$userId : string: id of the user

Return values

array<int, string> —

list of app ids

getDetails()

returns an array contains details about a config value


    public
                    getDetails(string $userId, string $app, string $key) : array<string|int, mixed>

[
  "app" => "myapp",
  "key" => "mykey",
  "value" => "its_value",
  "lazy" => false,
  "type" => 4,
  "typeString" => "string",
  'sensitive' => true
]

Parameters

$userId : string: id of the user
$app : string: id of the app
$key : string: config key

Return values

array<string|int, mixed>

getKeys()

Returns all keys stored in database, related to user+app.


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

Please note that the values are not returned.

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

Parameters

$userId : string: id of the user
$app : string: id of the app

Return values

array<int, string> —

list of stored config keys

getUserIds()

Get list of all userIds with config stored in database.


    public
                    getUserIds([string $appId = '' ]) : array<int, string>

If $appId is specified, will only limit the search to this value

WARNING: ignore any cache and get data directly from database.

Parameters

$appId : string = '': optional id of app

Return values

array<int, string> —

list of userIds

getValueArray()

Get config value assigned to a config key.


    public
                    getValueArray(string $userId, 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

$userId : string: id of the user
$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 $userId, 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

$userId : string: id of the user
$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

getValueFlags()

returns a bitflag related to config value


    public
                    getValueFlags(string $userId, string $app, string $key[, bool $lazy = false ]) : int

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

Parameters

$userId : string: id of the user
$app : string: id of the app
$key : string: config key
$lazy : bool = false: lazy loading

Return values

int —

a bitflag in relation to the config value

getValueFloat()

Get config value assigned to a config key.


    public
                    getValueFloat(string $userId, 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

$userId : string: id of the user
$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 $userId, 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

$userId : string: id of the user
$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()

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


    public
                    getValues(string $userId, 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

$userId : string: id of the user
$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

[key => value]

getValuesByApps()

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


    public
                    getValuesByApps(string $userId, string $key[, bool $lazy = false ][, ValueType|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

$userId : string: id of the user
$key : string: config key
$lazy : bool = false: search within lazy loaded config
$typedAs : ValueType|null = null: enforce type for the returned values

Return values

[appId => value]

getValuesByUsers()

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


    public
                    getValuesByUsers(string $app, string $key[, ValueType|null $typedAs = null ][, array<string|int, mixed>|null $userIds = null ]) : array<string, string|int|float|bool|array<string|int, mixed>>

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

WARNING: no caching, generate a fresh request

Parameters

$app : string: id of the app
$key : string: config key
$typedAs : ValueType|null = null: enforce type for the returned values
$userIds : array<string|int, mixed>|null = null: limit the search to a list of user ids

Return values

[userId => value]

getValueString()

Get user config assigned to a config key.


    public
                    getValueString(string $userId, 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

$userId : string: id of the user
$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 $userId, string $app, string $key[, bool|null $lazy = null ]) : ValueType

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

Parameters

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

Return values

ValueType —

type of the value

hasKey()

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


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

Parameters

$userId : string: id of the user
$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

isIndexed()

best way to see if a value is set as indexed (so it can be search)


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

Parameters

$userId : string: id of the user
$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

isLazy()

Returns if the config key stored in database is lazy loaded


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

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

Parameters

$userId : string: id of the user
$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 $userId, string $app, string $key[, bool|null $lazy = false ]) : bool

Parameters

$userId : string: id of the user
$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

searchUsersByValueBool()

List all users storing a specific config key/value pair.


    public
                    searchUsersByValueBool(string $app, string $key, bool $value) : Generator<string|int, string>

Returns a list of user ids.

WARNING: no caching, generate a fresh request

Parameters

$app : string: id of the app
$key : string: config key
$value : bool: config value

Return values

Generator<string|int, string>

searchUsersByValueInt()

List all users storing a specific config key/value pair.


    public
                    searchUsersByValueInt(string $app, string $key, int $value) : Generator<string|int, string>

Returns a list of user ids.

WARNING: no caching, generate a fresh request

Parameters

$app : string: id of the app
$key : string: config key
$value : int: config value

Return values

Generator<string|int, string>

searchUsersByValues()

List all users storing a specific config key/value pair.


    public
                    searchUsersByValues(string $app, string $key, array<string|int, mixed> $values) : Generator<string|int, string>

Returns a list of user ids.

WARNING: no caching, generate a fresh request

Parameters

$app : string: id of the app
$key : string: config key
$values : array<string|int, mixed>: list of possible config values

Return values

Generator<string|int, string>

searchUsersByValueString()

List all users storing a specific config key/value pair.


    public
                    searchUsersByValueString(string $app, string $key, string $value[, bool $caseInsensitive = false ]) : Generator<string|int, string>

Returns a list of user ids.

WARNING: no caching, generate a fresh request

Parameters

$app : string: id of the app
$key : string: config key
$value : string: config value
$caseInsensitive : bool = false: non-case-sensitive search, only works if $value is a string

Return values

Generator<string|int, string>

setValueArray()

Store a config key and its value in database


    public
                    setValueArray(string $userId, string $app, string $key, array<string|int, mixed> $value[, bool $lazy = false ][, int $flags = 0 ]) : 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

$userId : string: id of the user
$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
$flags : int = 0

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 $userId, 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

$userId : string: id of the user
$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 $userId, string $app, string $key, float $value[, bool $lazy = false ][, int $flags = 0 ]) : bool

If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using deleteKey() first

Parameters

$userId : string: id of the user
$app : string: id of the app
$key : string: config key
$value : float: config value
$lazy : bool = false: set config as lazy loaded
$flags : int = 0

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 $userId, string $app, string $key, int $value[, bool $lazy = false ][, int $flags = 0 ]) : 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

$userId : string: id of the user
$app : string: id of the app
$key : string: config key
$value : int: config value
$lazy : bool = false: set config as lazy loaded
$flags : int = 0

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 $userId, string $app, string $key, string $value[, bool $lazy = false ][, int $flags = 0 ]) : bool

If config value was previously stored as sensitive or lazy loaded, status cannot be altered without using deleteKey() first

Parameters

$userId : string: id of the user
$app : string: id of the app
$key : string: config key
$value : string: config value
$lazy : bool = false: set config as lazy loaded
$flags : int = 0

Return values

bool —

TRUE if value was different, therefor updated in database

updateGlobalIndexed()

switch sensitive loading status of a config key for all users


    public
                    updateGlobalIndexed(string $app, string $key, bool $indexed) : void

Warning: heavy on resources, MUST only be used on occ command or migrations

Parameters

$app : string: id of the app
$key : string: config key
$indexed : bool: TRUE to set as indexed, FALSE to unset

updateGlobalLazy()

switch lazy loading status of a config key for all users


    public
                    updateGlobalLazy(string $app, string $key, bool $lazy) : void

Warning: heavy on resources, MUST only be used on occ command or migrations

Parameters

$app : string: id of the app
$key : string: config key
$lazy : bool: TRUE to set as lazy loaded, FALSE to unset

updateGlobalSensitive()

switch sensitive loading status of a config key for all users


    public
                    updateGlobalSensitive(string $app, string $key, bool $sensitive) : void

Warning: heavy on resources, MUST only be used on occ command or migrations

Parameters

$app : string: id of the app
$key : string: config key
$sensitive : bool: TRUE to set as sensitive, FALSE to unset

updateIndexed()

switch indexed status of a config value


    public
                    updateIndexed(string $userId, string $app, string $key, bool $indexed) : bool

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

Parameters

$userId : string: id of the user
$app : string: id of the app
$key : string: config key
$indexed : bool: TRUE to set as indexed, FALSE to unset

Return values

bool —

TRUE if database update were necessary

updateLazy()

switch lazy loading status of a config value


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

Parameters

$userId : string: id of the user
$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 $userId, string $app, string $key, bool $sensitive) : bool

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

Parameters

$userId : string: id of the user
$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

IUserConfig in Application

What is lazy loading ?

Attributes

Table of Contents

Constants

Methods

Constants

FLAG_INDEXED

Tags

FLAG_SENSITIVE

Tags

Methods

clearCache()

Parameters

Tags

clearCacheAll()

Tags

deleteAllUserConfig()

Parameters

Tags

deleteApp()

Parameters

Tags

deleteKey()

Parameters

Tags

deleteUserConfig()

Parameters

Tags

getAllValues()

Parameters

Tags

Return values

getApps()

Parameters

Tags

Return values

getDetails()

Parameters

Tags

Return values

getKeys()

Parameters

Tags

Return values

getUserIds()

Parameters

Tags

Return values

getValueArray()

Parameters

Tags

Return values

getValueBool()

Parameters

Tags

Return values

getValueFlags()

Parameters

Tags

Return values

getValueFloat()

Parameters

Tags

Return values

getValueInt()

Parameters

Tags

Return values

getValues()

Parameters

Tags

Return values

getValuesByApps()

Parameters

Tags

Return values

getValuesByUsers()

Parameters

Tags

IUserConfig
in

Application