README

An API to synthesize low-level configuration.

This package is used by the framework ICanBoogie to configure its components.

Configurations are defined by a set of files that are called fragments. These fragments are used to synthesize the configuration of one or more components. When the same fragments are used to synthesize different configurations, these configurations are qualified as derived. Fragments are synthesized using callback functions called synthesizers. Configurations are managed by a Config instance. Finally, synthesized configurations can be cached, which cancel the cost of the synthesis.

Configuration fragments

A configuration fragment is a PHP file returning an array. Multiple fragments are used to synthesize a configuration, or derived configuration. They are usually located in "config" directories and are usually named after the config they are used to synthesize.

The configuration

The configuration is represented by a Config instance, which is used as an array to access specific configurations.

The following example demonstrates how to obtain the configuration routes:

<?php

/* @var \ICanBoogie\Config $config */

$routing_config = $config['routes'];

A NoSynthesizerDefined exception is thrown if there is no synthesizer defined for a configuration. A NoFragmentDefined exception is thrown if there is no fragment defined for a configuration.

Synthesizing a configuration

The synthesize() method of the Config instance is used to synthesize a configuration.

The following example demonstrates how a closure can be used to synthesize multiple fragments:

<?php

$config = $config->synthesize('core', function(array $fragments) {

	return call_user_func_array('ICanBoogie\array_merge_recursive', $fragments);

});

The exception NoFragmentDefined is thrown when no fragment of a specified type is defined.

Magic constructors

The synthesize() methods supports the magic constructors merge and recursive merge which respectively use the array_merge() and ICanBoogie\array_merge_recursive() functions. Thus, the following code examples are equivalent:

<?php

$core_config = $config->synthesize('core', function(array $fragments) {

	return call_user_func_array('ICanBoogie\array_merge_recursive', $fragments);
	
});

<?php

$core_config = $config->synthesize('core', 'merge recursive');

Configuration synthesizers

Synthesizers can be defined for each configuration, they are used when the config collection is used as an array:

<?php

$synthesizers = [ 'core' => 'merge recursive' ];
$config = new Config($paths, $synthesizers);
$core_config = $configs['core'];

Derived configurations

It is possible to synthesize a configuration from the same fragments as another configuration, such a configuration is qualified as derived.

For instance, events for the icanboogie/event package are defined in "hooks" fragments, the synthesizer for the events configuration filters the fragments data to extract what is relevant.

The following example demonstrates how to obtain the events configuration using the synthesize() method:

<?php

$events_config = $config->synthesize('events', 'ICanBoogie\Event\Hooks::synthesize_config', 'hooks');

The following example demonstrates how to define the synthesizer of the events configuration:

<?php

$config = new Config($paths, [

	'events' => [ 'ICanBoogie\Event\Hooks::synthesize_config', 'hooks' ]

]);

Caching synthesized configurations

Caching synthesized configurations removes the cost of synthesizing configurations by reusing the result of a previous synthesis. To enable caching, you just need to provide a cache implementing Storage.

<?php

$config = new Config($paths, $synthesizers, $cache);

Requirements

The package requires PHP 5.5 or later.

Installation

The recommended way to install this package is through Composer:

composer require icanboogie/config

Cloning the repository

The package is available on GitHub, its repository can be cloned with the following command line:

$ git clone https://github.com/ICanBoogie/Config.git

Documentation

The package is documented as part of the ICanBoogie framework documentation. You can generate the documentation for the package and its dependencies with the make doc command. The documentation is generated in the docs directory. ApiGen is required. You can later clean the directory with the make clean command.

Testing

The test suite is ran with the make test command. Composer is automatically installed as well as all dependencies required to run the suite. You can later clean the directory with the make clean command.

The package is continuously tested by Travis CI.

License

icanboogie/config is licensed under the New BSD License - See the LICENSE file for details.

icanboogie / config

Maintainers

Details

Add Maintainer

Remove Maintainer