README

QuEasy PHP Framework - Configuration

Package v-dem/queasy-config

This package contains a set of the classes intended for reading configuration files. Formats currently supported are:

• PHP
• INI
• JSON
• XML
• CLI (command-line)

Features

• Easy to use - just like nested arrays or objects. Also it's possible to use foreach() with config instances.
• Support for default option values.
• Support for multi-file configurations. You can split your config into many files as you wish without changing program code.
• Options inheritance. If an option is missing at current config level, it will look for this option on upper levels.
• Unified config interface. You can switch between config formats without changing your code.
• Easy to extend with other config formats.
• Regular expressions support (it's possible to get config options by regular expression).

Requirements

• PHP version 5.3 or higher

Reference

See Wiki page.

Installation

> composer require v-dem/queasy-config:master-dev

Usage

Let's imagine we have the following config.php:

return [
    'connection' => [
        'driver' => 'mysql',
        'host' => 'localhost',
        'name' => 'test',
        'user' => 'root',
        'password' => 'secret'
    ]
];

Or config.ini:

[connection]
driver = mysql
host = localhost
name = test
user = root
password = secret

Or config.json:

{
    "connection": {
        "driver": "mysql",
        "host": "localhost",
        "name": "test",
        "user": "root",
        "password": "secret"
    }
}

Or config.xml:

<?xml version="1.0">
<config>
    <connection
        driver="mysql"
        host="localhost"
        name="test"
        user="root"
        password="secret" />
</config>

You can mix different config types, for example top-level config of PHP type can refer to config files of other types.

Creating config instance

Include Composer autoloader:

require_once('vendor/autoload.php');

Create config instance (config file type will be detected by file name extension):

$config = new queasy\config\Config('config.php'); // Can be also '.ini', '.json' or '.xml'

Accessing config instance

Now you can address config sections and options these ways:

$databaseName = $config->database->name;

Or:

$databaseName = $config['database']['name'];

It's possible to use a default value if an option is missing:

// If 'host' is missing in config, 'localhost' will be used by default
$databaseHost = $config['database']->get('host', 'localhost');

A bit shorter way:

// If 'host' is missing in config, 'localhost' will be used by default
$databaseHost = $config['database']('host', 'localhost');

It's also possible to point that an option is required, and to throw ConfigException if this option is missing:

// Throw ConfigException if 'name' is missing
$databaseName = $config['database']->need('name');

How to check if a section or an option is present in config:

$hasDatabaseName = isset($config['database']);
$hasDatabaseName = isset($config['database']['name']);

If you don't want to check each section for presence when accessing a very nested option, you can use this trick:

// $databaseName will contain 'default' if 'name' and/or 'database' options are missing
$databaseName = $config->get('database', [])->get('name', 'default');

A bit shorter way:

// $databaseName will contain 'default' if 'name' and/or 'database' options are missing
$databaseName = $config('database', [])('name', 'default');

Multi-file configs

config.php:

return [
    'connection' => [
        'driver' => 'mysql',
        'host' => 'localhost',
        'name' => 'test',
        'user' => 'root',
        'password' => 'secret'
    ],
    'queries' => new queasy\config\Config('queries.php') // Can be config of another type (INI, JSON etc)
];

queries.php:

return [
    'selectActiveUsers' => 'SELECT * FROM `users` WHERE `is_active` = 1'
];

Accessing:

$config = new queasy\config\Config('config.php');
$query = $config['queries']['selectActiveUsers'];

Almost the same for other config formats:

config.ini:

[connection]
driver = mysql
host = localhost
name = test
user = root
password = secret
queries = "@queasy:new queasy\config\Config('queries.ini')"

There can be any PHP code after @queasy: so it's possible to use PHP constants etc. Be careful, eval() function is used to execute this expression.

Different config formats can be mixed this way.

Merging configs

You can use Config's merge() method to merge two configs. For example, you can have a default configuration and allow users to add or override some options:

$defaultConfig = new queasy\config\Config('defaults.php');
$optionalConfig = new queasy\config\Config($arrayWithOptionsToAddOrOverride);
$defaultConfig->merge($optionalConfig);

Using CLI config type

As an addition it's possible to use command-line arguments as config options source for CLI scripts (just use .cli extension, it will create appropriate loader):

$config = new queasy\config\Config('.cli');

Options should be passed this way (unfortunately only this is supported currently):

> php test.php option1=123 option2="some text"

I think it's useful to utilize merge() method there - default config file and optional arguments from command line.

Testing

Tests can be run with miminum PHP 7.2 version due to PHPUnit requirements. To run them use

> composer test