icanboogie / config
Synthesizes low-level configurations.
Installs: 3 737
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: >=5.5
- icanboogie/common: ^1.2|^2.0
- icanboogie/storage: ^2.0|^3.0
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.