README

Overview

An object-oriented interface to configuration. Configuration values can come from multiple sources, and be stacked in a hierarchy, allowing values to be overridden.

A configuration is a container of config values, which can use any number of configuration sources. A configuration source can be a JSON file, an external service, or anything you like. New configuration sources can be added by implementing the ConfigurationSource interface.

When adding sources to your configuration, their values are overlaid in the order that they are added. This allows newer, more specific, configuration sources to add extra configuration values, and to override values defined by previous sources.

This library is based very loosely on Archaius by Netflix.

Installation

The best way to autoload this package and its dependencies is to include the standard Composer autoloader, vendor/autoload.php.

Testing

The library's suite of unit tests can be run by calling vendor/bin/phpunit from the root of the repository.

Basic Usage

use \oneiota\config;

$config = new Configuration();
$config->addSource(new ConfigurationFile('myConfig.json'));

$config->hasConfig('foo'); // Returns TRUE if 'foo' is defined in the config.
$config->getRequiredConfig('foo'); // Throws an exception if 'foo' isn't defined.
$config->getOptionalConfig('foo', 'myDefaultValue'); // Returns a default value if 'foo' isn't defined.

Loading Configuration from Files

To load configuration from a file, use the ConfigurationFile class. At present, it can handle two types of file, JSON and PHP ini files.

PHP ini Files

PHP ini files are loaded with sections. For example,

[first_section]
foo = bar
bat = baz

[second_section]
foo = oof
cat = tac

will result in two top-level configuration keys (first_section and second_section). Each will be defined as an associative array, containing key-value pairs from that section --- ['foo'=>'bar', 'bat'=>'baz'] and ['foo'=>'oof', 'cat'=>'tac'] respectively.

Source Collections

Some sources are really collections of other sources. If you need to integrate a collection of sources, implement the ConfigurationSourceCollection interface. Calls to getSources() on collections return an array of ConfigurationSource instances in the order that they are to be applied. That means that the last source in the array takes highest priority.

Extensible Configuration Files

One example of this is the ExtensibleConfigurationFile class. This allows configuration files to extend other files by means of the $extends property. For example if we have two config files, a.json:

{
	"comment": "This is a.json",
	"foo": "bar",
	"bat": "baz"
}

and b.json:

{
	"comment": "This is b.json",
	"$extends": "a.json",
	"foo": "oof"
}

If we load b.json with ExtensibleConfigurationFile, the values from b.json will be stacked on top of those from a.json:

use \oneiota\config;

$config = new Configuration();

$source = new ExtensibleConfigurationFile('b.json');
$config->addSourceCollection($source);

$config->getRequiredConfig('foo'); // Returns 'oof'.
$config->getRequiredConfig('bat'); // Returns 'baz'.

Configuration in Code

Sometimes, you might just need to stuff config values into a container within your code. For this, you can use a SimpleConfigurationSource.

use \oneiota\config;

$config = new Configuration();

$source = new SimpleConfigurationSource();
$source->foo = 'bar';
$config->addSource($source);

It's worth noting that values from the source are copied into the configuration when it's first added, so subsequent changes to the source won't have any effect.

Alternatively, if you don't want to fiddle around with sources, you could use SimpleConfiguration.

$config = new \oneiota\config\SimpleConfiguration();

$config->foo = 'bar';
$config->getRequiredConfig('foo'); // Returns 'bar'.

oneiota / config

Maintainers

Details