Class Configure

Configuration class. Used for managing runtime configuration information.

Provides features for reading and writing to the runtime configuration, as well as methods for loading additional configuration files or storing runtime configuration for future use.

Namespace: Cake\Core
Link: https://book.cakephp.org/3/en/development/configuration.html

Property Summary

$_engines protected static

Cake\Core\Configure\ConfigEngineInterface[]

Configured engine classes, used to load config files from resources
$_hasIniSet protected static

bool|null

Flag to track whether or not ini_set exists.
$_values protected static

array

Array of values currently stored in Configure.

Method Summary

_getEngine() protected static

Get the configured engine. Internally used by Configure::load() and Configure::dump() Will create new PhpConfig for default if not configured yet.
check() public static

Returns true if given variable is set in Configure.
clear() public static

Clear all values stored in Configure.
config() public static

Add a new engine to Configure. Engines allow you to read configuration files in various formats/storage locations. CakePHP comes with two built-in engines PhpConfig and IniConfig. You can also implement your own engine classes in your application.
configured() public static

Gets the names of the configured Engine objects.
consume() public static

Used to read and delete a variable from Configure.
consumeOrFail() public static

Used to consume information stored in Configure. It's not possible to store null values in Configure.
delete() public static

Used to delete a variable from Configure.
drop() public static

Remove a configured engine. This will unset the engine and make any future attempts to use it cause an Exception.
dump() public static

Dump data currently in Configure into $key. The serialization format is decided by the config engine attached as $config. For example, if the 'default' adapter is a PhpConfig, the generated file will be a PHP configuration file loadable by the PhpConfig.
isConfigured() public static

Returns true if the Engine objects is configured.
load() public static

Loads stored configuration information from a resource. You can add config file resource engines with Configure::config().
read() public static

Used to read information stored in Configure. It's not possible to store null values in Configure.
readOrFail() public static

Used to get information stored in Configure. It's not possible to store null values in Configure.
restore() public static

Restores configuration data stored in the Cache into configure. Restored values will overwrite existing ones.
store() public static

Used to write runtime configuration into Cache. Stored runtime configuration can be restored using Configure::restore(). These methods can be used to enable configuration managers frontends, or other GUI type interfaces for configuration.
version() public static

Used to determine the current version of CakePHP.
write() public static

Used to store a dynamic variable in Configure.

Method Detail

_getEngine() ¶ protected static

_getEngine(string $config): Cake\Core\Configure\ConfigEngineInterface|false

Get the configured engine. Internally used by Configure::load() and Configure::dump() Will create new PhpConfig for default if not configured yet.

Parameters

string $config: The name of the configured adapter

Returns

Cake\Core\Configure\ConfigEngineInterface|false

check() ¶ public static

check(string $var): bool

Returns true if given variable is set in Configure.

Parameters

string $var: Variable name to check for

Returns

bool

clear() ¶ public static

clear(): bool

Clear all values stored in Configure.

Returns

bool

config() ¶ public static

config(string $name, Cake\Core\Configure\ConfigEngineInterface $engine): void

Add a new engine to Configure. Engines allow you to read configuration files in various formats/storage locations. CakePHP comes with two built-in engines PhpConfig and IniConfig. You can also implement your own engine classes in your application.

To add a new engine to Configure:

Configure::config('ini', new IniConfig());

Parameters

string $name: The name of the engine being configured. This alias is used later to read values from a specific engine.
Cake\Core\Configure\ConfigEngineInterface $engine: The engine to append.

Returns

void

configured() ¶ public static

configured(string|null $name = null): string[]|bool

Gets the names of the configured Engine objects.

Checking if a specific engine has been configured with this method is deprecated. Use Configure::isConfigured() instead.

Parameters

string|null $name optional: Engine name.

Returns

string[]|bool

consume() ¶ public static

consume(string $var): array|string|null

Used to read and delete a variable from Configure.

This is primarily used during bootstrapping to move configuration data out of configure into the various other classes in CakePHP.

Parameters

string $var: The key to read and remove.

Returns

array|string|null

consumeOrFail() ¶ public static

consumeOrFail(string $var): mixed

Used to consume information stored in Configure. It's not possible to store null values in Configure.

Acts as a wrapper around Configure::consume() and Configure::check(). The configure key/value pair consumed via this method is expected to exist. In case it does not an exception will be thrown.

Parameters

string $var: Variable to consume. Use '.' to access array elements.

Returns

mixed

Throws

RuntimeException
if the requested configuration is not set.

delete() ¶ public static

delete(string $var): void

Used to delete a variable from Configure.

Usage:

Configure::delete('Name'); will delete the entire Configure::Name
Configure::delete('Name.key'); will delete only the Configure::Name[key]

Parameters

string $var: the var to be deleted

Returns

void

Links

https://book.cakephp.org/3/en/development/configuration.html#deleting-configuration-data

drop() ¶ public static

drop(string $name): bool

Remove a configured engine. This will unset the engine and make any future attempts to use it cause an Exception.

Parameters

string $name: Name of the engine to drop.

Returns

bool

dump() ¶ public static

dump(string $key, string $config = 'default', string[] $keys = []): bool

Dump data currently in Configure into $key. The serialization format is decided by the config engine attached as $config. For example, if the 'default' adapter is a PhpConfig, the generated file will be a PHP configuration file loadable by the PhpConfig.

Usage

Given that the 'default' engine is an instance of PhpConfig. Save all data in Configure to the file my_config.php:

Configure::dump('my_config', 'default');

Save only the error handling configuration:

Configure::dump('error', 'default', ['Error', 'Exception'];

Parameters

string $key: The identifier to create in the config adapter. This could be a filename or a cache key depending on the adapter being used.
string $config optional: The name of the configured adapter to dump data with.
string[] $keys optional: The name of the top-level keys you want to dump. This allows you save only some data stored in Configure.

Returns

bool

Throws

Cake\Core\Exception\Exception
if the adapter does not implement a `dump` method.

isConfigured() ¶ public static

isConfigured(string $name): bool

Returns true if the Engine objects is configured.

Parameters

string $name: Engine name.

Returns

bool

load() ¶ public static

load(string $key, string $config = 'default', bool $merge = true): bool

Loads stored configuration information from a resource. You can add config file resource engines with Configure::config().

Loaded configuration information will be merged with the current runtime configuration. You can load configuration files from plugins by preceding the filename with the plugin name.

Configure::load('Users.user', 'default')

Would load the 'user' config file using the default config engine. You can load app config files by giving the name of the resource you want loaded.

Configure::load('setup', 'default');

If using default config and no engine has been configured for it yet, one will be automatically created using PhpConfig

Parameters

string $key: name of configuration resource to load.
string $config optional: Name of the configured engine to use to read the resource identified by $key.
bool $merge optional: if config files should be merged instead of simply overridden

Returns

bool

Links

https://book.cakephp.org/3/en/development/configuration.html#reading-and-writing-configuration-files

read() ¶ public static

read(string|null $var = null, mixed $default = null): mixed

Used to read information stored in Configure. It's not possible to store null values in Configure.

Usage:

Configure::read('Name'); will return all values for Name
Configure::read('Name.key'); will return only the value of Configure::Name[key]

Parameters

string|null $var optional: Variable to obtain. Use '.' to access array elements.
mixed $default optional: The return value when the configure does not exist

Returns

mixed

Links

https://book.cakephp.org/3/en/development/configuration.html#reading-configuration-data

readOrFail() ¶ public static

readOrFail(string $var): mixed

Used to get information stored in Configure. It's not possible to store null values in Configure.

Acts as a wrapper around Configure::read() and Configure::check(). The configure key/value pair fetched via this method is expected to exist. In case it does not an exception will be thrown.

Usage:

Configure::readOrFail('Name'); will return all values for Name
Configure::readOrFail('Name.key'); will return only the value of Configure::Name[key]

Parameters

string $var: Variable to obtain. Use '.' to access array elements.

Returns

mixed

Throws

RuntimeException
if the requested configuration is not set.

Links

https://book.cakephp.org/3/en/development/configuration.html#reading-configuration-data

restore() ¶ public static

restore(string $name, string $cacheConfig = 'default'): bool

Restores configuration data stored in the Cache into configure. Restored values will overwrite existing ones.

Parameters

string $name: Name of the stored config file to load.
string $cacheConfig optional: Name of the Cache configuration to read from.

Returns

bool

store() ¶ public static

store(string $name, string $cacheConfig = 'default', array|null $data = null): bool

Used to write runtime configuration into Cache. Stored runtime configuration can be restored using Configure::restore(). These methods can be used to enable configuration managers frontends, or other GUI type interfaces for configuration.

Parameters

string $name: The storage name for the saved configuration.
string $cacheConfig optional: The cache configuration to save into. Defaults to 'default'
array|null $data optional: Either an array of data to store, or leave empty to store all values.

Returns

bool

version() ¶ public static

version(): string

Used to determine the current version of CakePHP.

Usage

Configure::version();

Returns

string

write() ¶ public static

write(string|array $config, mixed $value = null): bool

Used to store a dynamic variable in Configure.

Usage:

Configure::write('One.key1', 'value of the Configure::One[key1]');
Configure::write(['One.key1' => 'value of the Configure::One[key1]']);
Configure::write('One', [
    'key1' => 'value of the Configure::One[key1]',
    'key2' => 'value of the Configure::One[key2]'
]);

Configure::write([
    'One.key1' => 'value of the Configure::One[key1]',
    'One.key2' => 'value of the Configure::One[key2]'
]);

Parameters

string|array $config: The key to write, can be a dot notation value. Alternatively can be an array containing key(s) and value(s).
mixed $value optional: Value to set for var

Returns

bool

Links

https://book.cakephp.org/3/en/development/configuration.html#writing-configuration-data

Property Detail

`$_engines` ¶ protected static

Configured engine classes, used to load config files from resources

Type

Cake\Core\Configure\ConfigEngineInterface[]

`$_hasIniSet` ¶ protected static

Flag to track whether or not ini_set exists.

Type

bool|null

`$_values` ¶ protected static

Array of values currently stored in Configure.

Type

array

Namespaces

Class Configure

Property Summary

Method Summary

_getEngine() protected static

check() public static

clear() public static

config() public static

configured() public static

consume() public static

consumeOrFail() public static

delete() public static

drop() public static

dump() public static

isConfigured() public static

load() public static

read() public static

readOrFail() public static

restore() public static

store() public static

version() public static

write() public static

Method Detail

_getEngine() ¶ protected static

Parameters

Returns

check() ¶ public static

Parameters

Returns

clear() ¶ public static

Returns

config() ¶ public static

Parameters

Returns

configured() ¶ public static

Parameters

Returns

consume() ¶ public static

Parameters

Returns

consumeOrFail() ¶ public static

Parameters

Returns

Throws

delete() ¶ public static

Parameters

Returns

Links

drop() ¶ public static

Parameters

Returns

dump() ¶ public static

Usage

Parameters

Returns

Throws

isConfigured() ¶ public static

Parameters

Returns

load() ¶ public static

Parameters

Returns

Links

read() ¶ public static

Parameters

Returns

Links

readOrFail() ¶ public static

Parameters

Returns

Throws

Links

restore() ¶ public static

Parameters

Returns

store() ¶ public static

Parameters

Returns

version() ¶ public static

Returns

`$_engines` ¶ protected static

`$_hasIniSet` ¶ protected static

`$_values` ¶ protected static