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.
Property Summary
-
$_engines protected static
array<Cake\Core\Configure\ConfigEngineInterface>
Configured engine classes, used to load config files from resources
-
$_hasIniSet protected static
bool|null
Flag to track whether ini_set exists.
-
$_values protected static
array<string, mixed>
Array of values currently stored in Configure.
Method Summary
-
_getEngine() protected static
Get the configured engine. Internally used by
Configure::load()
andConfigure::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|null
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|null
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
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(): array<string>
Gets the names of the configured Engine objects.
Returns
array<string>
consume() ¶ public static
consume(string $var): mixed
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
mixed
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
Cake\Core\Exception\CakeException
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
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', list<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.
-
list<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\CakeException
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
Throws
Cake\Core\Exception\CakeException
if the $config engine is not found
Links
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
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
Cake\Core\Exception\CakeException
if the requested configuration is not set.
Links
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(array<string, mixed>|string $config, mixed $value = null): void
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
-
array<string, mixed>|string
$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 the given key.
Returns
void