Config

PHP library for simple configuration management -- 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

Like this project? Keep me caffeinated by making a donation.

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

Parameter	Description
$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

Parameter	Description
$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

Parameter	Description
$key	Unique configuration option key
$value	Default value to return if option does not exist

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

Parameter	Description
$key	Unique configuration option key

Example

$config = new Config([
    'hostname' => 'localhost'
]);

$config->has('hostname'); // Returns true
$config->has('port');     // Returns false

---

load

Load configuration options from a file or directory.

Config::load( string $path [, string $prefix = null [, bool $override = true ]] ) : self

Parameter	Description
$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

Parameter	Description
$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

Parameter	Description
$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

Please report bugs to the GitHub Issue Tracker.

Copyright

This project is liscensed under the MIT License.