Puzzle-configuration 
Hide configuration implementation behind common interface., (*1)
Some advantages :
* Application does not depend upon configuration implementation details
* Application does not have to manage filesystem issues (for filesystem based implementations)
* Application can be easily tested, even for configuration edge cases (missing or wrong configuration values)
* Define configuration as a service in your dependency injection container, (*2)
QA
| Service |
Result |
| CI |
 |
| Packagist |
 
|
Installation
Use composer :, (*3)
{
"require": {
"puzzle/configuration" : "~8.3"
}
}
PHP 8.0 & 8.1 users please use puzzle/configuration 5.x, (*4)
PHP 7.x users please use puzzle/configuration 4.x, (*5)
PHP 5.6 users please use puzzle/configuration 3.x, (*6)
Documentation
Configuration as a service
<?php
class Example
{
public function __construct(Puzzle\Configuration $config)
{
$threshold = $config->read('app/detection/threshold');
}
}
The way the configuration value is read depends on the chosen implementation., (*7)
Up to now, 2 implementations are provided :
* Memory (for unit testing purpose)
* Yaml (based on Symfony/Yaml)., (*8)
For YAML one, 'app/detection/threshold' means detection[thresold] in app.yml file.
When you instanciate YamlConfiguration object, you need to provide where yaml files can be found :, (*9)
<?php
$fileSystem = new Gaufrette\Filesystem(
new Local('path/to/yaml/files/root/dir')
);
$config = new Puzzle\Configuration\Yaml($fileSystem);
$example = new Example($config);
# app.yml
detection:
threshold: 3
Unit testing
<?php
$config = new Puzzle\Configuration\Memory(array(
'app/detection/threshold' => 2
);
$example = new ExampleTest($config);
Default values
<?php
$configuration->read('a/b/c', 'default value if a/b/c does not exist');
But if a/b/c is required :, (*10)
<?php
// will throw an exception if a/b/c does not exist
$configuration->readRequired('a/b/c');
Fallback strategy
<?php
// Since 1.5.0
// returns value associated to first existing key
// will throw an exception if none exist
$configuration->readFirstExisting('a/b/c', 'd/e/f', 'x/y/z');
Override configuration
If you need some configuration to (partially or not) override another one :, (*11)
<?php
// Since 1.6.0
$defaultFileSystem = new Gaufrette\Filesystem(
new Local('path/to/yaml/files/root/dir')
);
$defaultConfig = new Puzzle\Configuration\Yaml($defaultFileSystem);
$fileSystem = new Gaufrette\Filesystem(
new Local('path/to/another/config/files')
);
$localConfig = new Puzzle\Configuration\Yaml($fileSystem);
$config = new Puzzle\Configuration\Stacked();
$config->overrideBy($defaultConfig)
->overrideBy($localConfig);
// values will be read in localConfig first. They will be read in default config only if they don't exist in local one.
Another example :, (*12)
<?php
$fileSystem = new Gaufrette\Filesystem(
new Local('path/to/yaml/files/root/dir')
);
$defaultConfig = new Puzzle\Configuration\Yaml($fileSystem);
$overrideConfig = new Puzzle\Configuration\Memory(array(
'app/detection/threshold' => 2
);
$config = new Puzzle\Configuration\Stacked();
$config->overrideBy($defaultConfig)
->overrideBy($overrideConfig);
You can add as many as configuration instances you want in the stack. The last inserted is the most prioritary., (*13)
If you want to add the least prioritary, use the addBase() method :, (*14)
<?php
// Since 2.0.0
$config = new Puzzle\Configuration\Stacked();
$config->overrideBy($overrideConfig)
->addBase($defaultConfig);
Prefixed configuration
You can use automatic prefix decorator PrefixedConfiguration. It can be useful for "namespace like" configurations such as loggers or multiple databases ones., (*15)
# logger.yml
app:
filename: app.log
verbosity: INFO
users:
filename: users.log
verbosity: WARNING
<?php
// Since 1.7.0
$fileSystem = new Gaufrette\Filesystem(
new Local('path/to/yaml/files/root/dir')
);
$config = new Puzzle\Configuration\Yaml($fileSystem);
$config = new Puzzle\PrefixedConfiguration($config, "logger/$loggerName");
$filename = $config->readRequired('filename');
$verbosity = $config->readRequired('verbosity');
Changelog
5.x --> 8.3, (*16)
- Drop php 8.0 & 8.1 support. Minimal version is 8.3
- Version names are now match the PHP version as the library does not need to functionaly evolve anymore
- Get rid of Gaufrette. Own interface is provided, please implements it. A Gaufrette adapter is provided for smooth migration
4.x --> 5.x, (*17)
- Drop php 7 support. Minimal version is 8.0
3.x --> 4.x, (*18)
-
Drop php 5.6 & 7.0 support. Minimal version is 7.1.0, (*19)
2.x --> 3.x, (*20)
-
Drop php 5.5 support. Minimal version is 5.6.0, (*21)
1.x -> 2.x, (*22)
- Drop php 5.4 support. Minimal version is 5.5.0
Wallogit.com
