phlak / config
Config loading and management
Installs: 178 174
Dependents: 9
Suggesters: 0
Security: 0
Stars: 50
Watchers: 6
Forks: 11
Open Issues: 3
Requires
- php: ^8.0 || ^8.1 || ^8.2
- symfony/yaml: ^5.0 || ^6.0
- yosymfony/toml: ^1.0
Requires (Dev)
- phlak/coding-standards: ^2.2
- phpstan/phpstan: ^1.10
- psy/psysh: ^0.11
- yoast/phpunit-polyfills: ^2.0
README
PHP library for simple configuration management -- Created by Chris Kankiewicz (@PHLAK)
Introduction
Config is a simple PHP configuration management library supporting multiple configuration file formats and an expressive API.
Supported file formats:
- PHP
- INI
- JSON
- TOML
- YAML
- XML
Requirements
- PHP >= 7.1
Install with Composer
composer require phlak/config
Initializing the Client
First, import Config:
use PHLAK\Config\Config;
Then instantiate the class:
$config = new Config($context, $prefix = null);
Where $context
is one of the following:
- A path to a supported file type
- A directory path containing one or more supported file types
- An array of configuration options
And $prefix
is a string to be used as a key prefix for options of this Config object.
Configuration File Formats
PHP
A PHP configuration file must have the .php
file extension, be a valid PHP
file and and return a valid PHP array.
Example PHP file
<?php return [ 'driver' => 'mysql', 'drivers' => [ 'sqlite' => [ 'database' => 'database.sqlite', 'prefix' => '' ], 'mysql' => [ 'host' => 'localhost', 'database' => 'blog', 'username' => 'blogger', 'password' => 'hunter2', 'charset' => 'utf8', 'prefix' => '' ] ] ];
INI
An INI configuration file must have the .ini
file extension and be a valid INI
file.
Example INI file
driver = mysql [drivers] sqlite[database] = database.sqlite sqlite[prefix] = mysql[host] = localhost mysql[database] = blog mysql[username] = blogger mysql[password] = hunter2 mysql[charset] = utf8 mysql[prefix] =
JSON
A JSON configuration file must have the .json
file extension and contain a
valid JSON object.
Example JSON file
{ "driver": "mysql", "drivers": { "sqlite": { "database": "database.sqlite", "prefix": "" }, "mysql": { "host": "localhost", "database": "blog", "username": "blogger", "password": "hunter2", "charset": "utf8", "prefix": "" } } }
TOML
A TOML configuration file must have the .toml
file extension and be a valid
TOML file.
Example TOML file
driver = 'mysql' [drivers.sqlite] database = 'database.sqlite' prefix = '' [drivers.mysql] host = 'localhost' database = 'blog' username = 'blogger' password = 'hunter2' charset = 'utf8' prefix = ''
YAML
A YAML configuration file must have the .yaml
file extension, be a valid YAML
file.
Example YAML file
driver: mysql drivers: sqlite: database: database.sqlite prefix: mysql: host: localhost database: blog username: blogger password: hunter2 charset: utf8 prefix:
XML
A XML configuration file must have the .xml
file extension and contain valid
XML.
Example XML file
<?xml version='1.0'?> <database> <driver>mysql</driver> <drivers> <sqlite> <database>database.sqlite</database> <prefix></prefix> </sqlite> <mysql> <host>localhost</host> <database>blog</database> <username>blogger</username> <password>hunter2</password> <charset>utf8</charset> <prefix></prefix> </mysql> </drivers> </database>
Usage
__construct
Create a new Config object.
Config::__construct( mixed $context [, string $prefix = null ] ) : Config
$context
- Raw array of configuration options or path to a configuration file or directory containing one or more configuration files
$prefix
- A key under which the loaded config will be nested
Examples
Create a new Config object from a YAML file.
$config = new Config('path/to/conifg.yaml');
Create a new Config object from a directory of config files.
$config = new Config('path/to/conifgs/');
Create a new Config object from an array.
$config = new Config([ 'hostname' => 'localhost', 'port' => 12345 ]);
set
Store a config value with a specified key.
Config::set( string $key, mixed $value ) : bool
$key
- Unique configuration option key
$value
- Config item value
Example
$config->set('hostname', 'localhost'); $config->set('port', 12345);
get
Retrieve a configuration option via a provided key.
Config::get( string $key [, mixed $default = null ] ) : mixed
$key
- Unique configuration option key
$value
- Config item value
Examples
// Return the hostname option value or null if not found. $config->get('hostname');
Define a default value to return if the option is not set.
// Returns 'localhost' if hostname option is not set $config->get('hostname', 'localhost');
has
Check for the existence of a configuration item.
Config::has( string $key ) : bool
$key
- Unique configuration option key
Example
$config = new Config([ 'hostname' => 'localhost' ]); $config->has('hostname'); // Returns true $config->has('port'); // Returns false
append
Append a value onto an existing array configuration option.
Config::append( string $key, mixed $value ) : bool
$key
- Unique configuration option key
$value
- Config item value
Example
Append baz
to the tags
config item array.
$config->set('tags', ['foo', 'bar']) $config->append('tags', 'baz'); // ['foo', 'bar', 'baz']
prepend
Prepend a value onto an existing array configuration option.
Config::append( string $key, mixed $value ) : bool
$key
- Unique configuration option key
$value
- Config item value
Example
Prepend baz
to the tags
config item array.
$config->set('tags', ['foo', 'bar']) $config->append('tags', 'baz'); // ['baz', 'foo', 'bar']
unset
Unset a configuration option via a provided key.
Config::unset( string $key ) : bool
$key
- Unique configuration option key
Example
$config->unset('hostname');
load
Load configuration options from a file or directory.
Config::load( string $path [, string $prefix = null [, bool $override = true ]] ) : self
$path
- Path to configuration file or directory
$prefix
- A key under which the loaded config will be nested
$override
- Whether or not to override existing options with values from the loaded file
Examples
Load a single additional file.
$conifg->load('path/to/config.php');
Load an additional file with a prefix.
$config->load('databaes.php', 'database');
Load an additional file without overriding existing values.
$config->load('additional-options.php', null, false);
merge
Merge another Config object into this one.
Config::merge( Config $config [, bool $override = true ] ) : self
$config
- Instance of Config
$override
- Whether or not to override existing options with values from the merged config object
Examples
Merge $anotherConfig into $config and override values in $config
with values
from $anotherConfig
.
$anotherConfig = new Config('some/config.php'); $config->merge($anotherConfig);
Merge $anotherConfig
into $config
without overriding any values. Duplicate
values in $anotherConfig
will be lost.
$anotherConfig = new Config('some/config.php'); $config->merge($anotherConfig, false);
split
Split a sub-array of configuration options into it's own Config object.
Config::split( string $key ) : Config
$key
- Unique configuration option key
Example
$config = new Config([ 'foo' => 'foo', 'bar' => [ 'baz' => 'barbaz' ], ]); $barConfig = $config->split('bar'); $barConfig->get('baz'); // Returns 'barbaz'
toArray
Return the entire configuration as an array.
Config::toArray( void ) : array
Example
$config = new Config(['foo' => 'foo']); $config->toArray(); // Returns ['foo' => 'foo']
Troubleshooting
For general help and support join our GitHub Discussion or reach out on Twitter.
Please report bugs to the GitHub Issue Tracker.
Copyright
This project is liscensed under the MIT License.