hassankhan / config
Lightweight configuration file loader that supports PHP, INI, XML, JSON, and YAML files
Installs: 12 046 625
Dependents: 212
Suggesters: 0
Security: 0
Stars: 973
Watchers: 36
Forks: 137
Open Issues: 25
Requires
- php: >=7.4
Requires (Dev)
- phpunit/phpunit: ^9.5
- scrutinizer/ocular: ^1.9
- squizlabs/php_codesniffer: ^3.6
- symfony/yaml: ^5.4
Suggests
- symfony/yaml: ^5.4
- dev-develop
- 3.2.0
- 3.1.0
- 3.0.1
- 3.0.0
- 2.2.0
- v2.1.0
- 2.0.2
- 2.0.1
- 2.0.0
- 1.1.0
- 1.0.1
- 1.0.0
- 0.11.2
- 0.11.1
- 0.11.0
- 0.10.0
- 0.9.1
- 0.9.0
- 0.8.2
- 0.8.1
- 0.8.0
- 0.7.1
- 0.7.0
- 0.6.0
- 0.5.0
- 0.4.0
- 0.3.0
- 0.2.1
- 0.2.0
- 0.1.0
- 0.0.1
- dev-master
- dev-feature/165
- dev-feature/add-new-php-versions-to-matrix
- dev-fix/xls-with-attributes
- dev-feature/major-changes
This package is auto-updated.
Last update: 2024-12-10 09:10:02 UTC
README
Config is a file configuration loader that supports PHP, INI, XML, JSON, YML, Properties and serialized files and strings.
Requirements
Config requires PHP 7.4+.
IMPORTANT: If you want to use YAML files or strings, require the Symfony Yaml component in your
composer.json
.
Installation
The supported way of installing Config is via Composer.
$ composer require hassankhan/config
Usage
Config is designed to be very simple and straightforward to use. All you can do with it is load, get, and set.
Loading files
The Config
object can be created via the factory method load()
, or
by direct instantiation:
use Noodlehaus\Config; use Noodlehaus\Parser\Json; // Load a single file $conf = Config::load('config.json'); $conf = new Config('config.json'); // Load values from multiple files $conf = new Config(['config.json', 'config.xml']); // Load all supported files in a directory $conf = new Config(__DIR__ . '/config'); // Load values from optional files $conf = new Config(['config.dist.json', '?config.json']); // Load a file using specified parser $conf = new Config('configuration.config', new Json);
Files are parsed and loaded depending on the file extension or specified parser. If the parser is specified, it will be used for all files. Note that when loading multiple files, entries with duplicate keys will take on the value from the last loaded file.
When loading a directory, the path is glob
ed and files are loaded in by
name alphabetically.
Warning: Do not include untrusted configuration in PHP format. It could contain and execute malicious code.
Loading string
Configuration from string can be created via the factory method load()
or
by direct instantiation, with argument $string
set to true
:
use Noodlehaus\Config; use Noodlehaus\Parser\Json; use Noodlehaus\Parser\Yaml; $settingsJson = <<<FOOBAR { "application": { "name": "configuration", "secret": "s3cr3t" }, "host": "localhost", "port": 80, "servers": [ "host1", "host2", "host3" ] } FOOBAR; $settingsYaml = <<<FOOBAR application: name: configuration secret: s3cr3t host: localhost port: 80 servers: - host1 - host2 - host3 FOOBAR; $conf = Config::load($settingsJson, new Json, true); $conf = new Config($settingsYaml, new Yaml, true);
Warning: Do not include untrusted configuration in PHP format. It could contain and execute malicious code.
Getting values
Getting values can be done in three ways. One, by using the get()
method:
// Get value using key $debug = $conf->get('debug'); // Get value using nested key $secret = $conf->get('security.secret'); // Get a value with a fallback $ttl = $conf->get('app.timeout', 3000);
The second method, is by using it like an array:
// Get value using a simple key $debug = $conf['debug']; // Get value using a nested key $secret = $conf['security.secret']; // Get nested value like you would from a nested array $secret = $conf['security']['secret'];
The third method, is by using the all()
method:
// Get all values $data = $conf->all();
Setting values
Although Config supports setting values via set()
or, via the
array syntax, any changes made this way are NOT reflected back to the
source files. By design, if you need to make changes to your
configuration files, you have to do it manually.
$conf = Config::load('config.json'); // Sample value from our config file assert($conf['secret'] == '123'); // Update config value to something else $conf['secret'] = '456'; // Reload the file $conf = Config::load('config.json'); // Same value as before assert($conf['secret'] == '123'); // This will fail assert($conf['secret'] == '456');
Saving config
It is possible to save the config back to a file in any of the supported formats except PHP.
$config = Config::load('config.json'); $ini = $config->toString(new Ini()); // Encode to string if you want to save the file yourself $config->toFile('config.yaml'); $config->toFile('config.txt', new Serialize()); // you can also force the writer
Using with default values
Sometimes in your own projects you may want to use Config for storing
application settings, without needing file I/O. You can do this by extending
the AbstractConfig
class and populating the getDefaults()
method:
class MyConfig extends AbstractConfig { protected function getDefaults() { return [ 'host' => 'localhost', 'port' => 80, 'servers' => [ 'host1', 'host2', 'host3' ], 'application' => [ 'name' => 'configuration', 'secret' => 's3cr3t' ] ]; } }
Merging instances
You may want merging multiple Config instances:
$conf1 = Config::load('conf1.json'); $conf2 = Config::load('conf2.json'); $conf1->merge($conf2);
Examples of supported configuration files
Examples of simple, valid configuration files can be found here.
Performance
Please note that there is a significant drop in performance with configurations in the yaml
format: Load configuration was 1ms in both json
and php
while the same configuration was 5ms with yaml.
Testing
$ phpunit
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email contact@hassankhan.me instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.