v-dem/queasy-config

Configuration classes (currently supports PHP, INI and JSON configs), part of Queasy PHP Framework

, _(*1)

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:, _(*2)

• 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., _(*3)

Installation

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

Usage

Let's imagine we have the following config.php:, _(*4)

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

Or config.ini:, _(*5)

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

Or config.json:, _(*6)

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

Or config.xml:, _(*7)

<?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., _(*8)

Creating config instance

Include Composer autoloader:, _(*9)

require_once('vendor/autoload.php');

Create config instance (config file type will be detected by file name extension):, _(*10)

$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:, _(*11)

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

Or:, _(*12)

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

It's possible to use a default value if an option is missing:, _(*13)

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

A bit shorter way:, _(*14)

// 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:, _(*15)

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

How to check if a section or an option is present in config:, _(*16)

$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:, _(*17)

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

A bit shorter way:, _(*18)

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

Multi-file configs

config.php:, _(*19)

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:, _(*20)

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

Accessing:, _(*21)

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

Almost the same for other config formats:, _(*22)

config.ini:, _(*23)

[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., _(*24)

Different config formats can be mixed this way., _(*25)

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:, _(*26)

$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):, _(*27)

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

Options should be passed this way (unfortunately only this is supported currently):, _(*28)

> 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., _(*29)

Testing

Tests can be run with miminum PHP 7.2 version due to PHPUnit requirements. To run them use, _(*30)

> composer test