Config
PHP library for simple configuration management
Install / Use
/learn @PHLAK/ConfigREADME
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.
<?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.
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.
{
"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.
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.
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.
<?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
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
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
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
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
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
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
Example
$config->unset('hostname');
load
Load configuration options from a file or directory.
Config::load( string $path [, string $prefix = null [, bool $override = true ]] ) : self
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
