ckr / config
Simple access to multi dimensional arrays, useful for configuration data
Requires
- php: >=5.5.0
- ckr/arraymerger: ^2.0.0
Requires (Dev)
- phpspec/phpspec: ~2.3
- phpunit/phpunit: ~4.8
This package is not auto-updated.
Last update: 2024-10-26 17:19:06 UTC
README
This package provides a class to manage hierarchical data. A common use case is configuration data.
Note that this package does not provide any readers or writers for config files of different formats. Instead it wraps php arrays and provides easier access to its values.
Why?
I was tired of using too many isset
throghout all my code. The main
advantage of this library is, that you can request
an arbitrary deeply nested value, and provide a default value which
should be returned in case the requested value does not exist:
$myConfig = [ 'root' => [ 'specific' => ['key' => 'val'], ], ]; // plain php is a bit ugly... $theSpecific = isset($myConfig['root']['specific']['key']) ? $myConfig['root']['specific']['key'] : null; $theGeneral = isset($myConfig['root']['key']) ? $myConfig['root']['key'] : false; // ... but with a `Config` it looks nicer: $config = new Ckr\Config\Config($myConfig); $theSpecific = $config->get('root/specific/key'); $theGeneral = $config->get('root/key', false);
Actually, if you're using PHP7, this problem is solved:
// valid code in PHP7 $theSpecific= $myConfig['root']['specific']['key'] ?? null; $theGeneral = $myConfig['root']['key'] ?? false;
However, as I prefer to specify the path as root/specific/key
instead
of ['root']['specific']['key']
, I still use this library in my
PHP7 projects.
Usage
You start with a hierarchical data structure, defined as multi dimensional array:
$myConfig = [ 'mode' => 'production', 'logging' => [ 'factory' => 'Your\\Logging\\Factory', 'loggers' => [ [ 'type' => 'file', 'path' => '/path/to/logs', 'level' => 'warn', ], [ 'type' => 'email', 'addr' => 'someone@somewhere.com', 'level' => 'critical', ] ], ] ];
Then you can wrap it in a Config
object:
use Ckr\Config\Config;
$c = new Config($myConfig);
You can ask for a simple value with get
:
$mode = $c->get('mode', 'dev');
In the example above, "dev" is the default mode. It is returned, if the key 'mode' does not exist in the config data.
You can ask for a value which is nested in a child array by providing a path of keys, separated
by a Slash /
:
$loggingFactoryClass = $c->get('logging/factory');
If any of the used path parts (keys) don't exist, the default value (null
if
not explicitly specified) is returned.
Say you want to use all of the logging data, e.g. to instantiate your logging instance. For this, you can get a child config object:
$loggingConfig = $c->child('logging'); /* @var $loggingConfig Config */ // we can now provide only the relevant data to thr logging factory $myLoggingFactory = new $loggingFactoryClass; $logger = $myLoggingFactory->create($loggingConfig); // the logging factory "sees" only the data of the "logging" child array public function create(Config $cfg) { $loggers = $cfg->get('loggers'); // $loggers is an array foreach ($loggers as $logger) { /* ... */ } // ... }
To summarize:
Config::get
will always return the value as it was defined originally. No matter, if the value is an array, a class instance, a function or a scalar value.Config::child
expects the given path to point to an (associative) array. It wraps this array in aConfig
and returns that object.
A new value can be set using Config::set
:
$newConfig = $c->set('logging/factory', 'AnotherFactoryClass');
This method returns a new instance with a specific part of the config updated (or newly set).
This may be useful if you want to construct a complete configuration object
in multiple steps from different parts of your code,
e.g. to allow different modules to register their configuration or factories.
In the above example, $newConfig
has a value of 'AnotherFactoryClass'
at the path
logging/factory, where the $c
instance is not modified and still has the old value.
(Note that this behaviour is new in Version 2.0, former versions did update the data in place).