Skip to content
This repository has been archived by the owner on Jan 29, 2020. It is now read-only.

Initial documentation #7

Merged
merged 1 commit into from
Apr 24, 2017
Merged

Initial documentation #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
218 changes: 12 additions & 206 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,12 @@
# zend-config-aggregator

[![Build Status](https://travis-ci.org/zendframework/zend-config-aggregator.svg?branch=master)](https://travis-ci.org/zendframework/zend-config-aggregator)
[![Build Status](https://travis-ci.org/zendframework/zend-config-aggregator.svg?branch=master)](https://travis-ci.org/zendframework/zend-config-aggregator)

Lightweight library for collecting and merging configuration from different sources.

While designed for [Expressive](https://github.com/zendframework/zend-expressive)
applications, it can work with any PHP project for aggregating and returning
merged configuration, from either a variety of configuration formats or
"configuration providers", invokable classes returning an array of configuration
(or a PHP generator). It also supports configuration caching.
Aggregates and merges configuration, from a variety of formats. Supports caching for fast bootstrap in production environments.

## Usage

### Config files

At the basic level, `ConfigAggregator` can be used to merge PHP-based
configuration files:
Standalone `ConfigAggregator` can be used to merge PHP-based configuration files:

```php
use Zend\ConfigAggregator\ConfigAggregator;
Expand Down Expand Up @@ -63,207 +54,22 @@ array(3) {
}
```

Configuration is merged in the same order as it is passed, with later entries
having precedence.

### Config providers

`ConfigAggregator` works by aggregating "Config Providers" passed to its
constructor. Each provider should be a callable, returning a configuration
array (or a PHP generator) to be merged.

```php
$aggregator = new ConfigAggregator([
function () {
return ['foo' => 'bar'];
},
new PhpFileProvider('*.global.php'),
]);
var_dump($aggregator->getMergedConfig());
```

If the provider is a class name, the aggregator automatically instantiates it.
This can be used to mimic the Zend Framework module system: you can specify a
list of config providers from different packages, and aggregated configuration
will be available to your application.

As a library owner, you can distribute your own configuration providers that
provide default values for use with your library.

As an example:

```php
class ApplicationConfig
{
public function __invoke()
{
return ['foo' => 'bar'];
}
}

$aggregator = new ConfigAggregator(
[
ApplicationConfig::class,
new PhpFileProvider('*.global.php'),
]
);
var_dump($aggregator->getMergedConfig());
```

Output from both examples will be the same:

```php
array(4) {
'foo' =>
string(3) "bar"
'db' =>
array(1) {
'dsn' =>
string(9) "mysql:..."
}
'cache_storage' =>
string(5) "redis"
'redis' =>
array(0) {
}
}
```

### Caching

Merging configuration on every request is not performant. As such,
zend-config-aggregator also provides the ability to enable a filesystem-based
configuration cache.

To enable the configuration cache, pass a cache file name as the second
parameter to the `ConfigAggregator` constructor:

```php
$aggrgator = new ConfigAggregator(
[
function () { return [ConfigAggregator::ENABLE_CACHE => true]; },
new PhpFileProvider('*.global.php'),
],
'data/config-cache.php'
);
```

When a cache file is specified, you will also need to add the
`config_cache_enabled` key (which you can also specify via the
`ConfigAggregator::ENABLE_CACHE` constant) somewhere within one of your
configuration providers, and set it to boolean `true`. Using this approach, if
you were to use the globbing pattern `{{,*.}global,{,*.}local}.php` (or similar)
with the `PhpFileProvider`, you could drop a file named `enable-cache.local.php`
into your production deployment with the following contents in order to enable
configuration caching in production:

```php
<?php
use Zend\ConfigAggregator\ConfigAggregator;

return [
ConfigAggregator::ENABLE_CACHE => true,
];
```

When caching is enabled, the `ConfigAggregator` does not iterate config
providers. Because of that it is very fast, but after it is enabled you cannot
make any changes to configuration without clearing the cache. **Caching should
be used only in a production environment**, and your deployment process should
clear the cache.

### Generators
Configuration is merged in the same order as it is passed, with later entries having precedence.

Config providers can be written as generators. This way single callable can provide
multiple configurations:

```php
use Zend\ConfigAggregator\ConfigAggregator;
use Zend\Stdlib\Glob;

$aggregator = new ConfigAggregator([
function () {
foreach (Glob::glob('data/*.global.php', Glob::GLOB_BRACE) as $file) {
yield include $file;
}
}
]
);
var_dump($aggregator->getMergedConfig());
```

The providers `PhpFileProvider` is implemented using generators.


## Available config providers

### PhpFileProvider

Loads configuration from PHP files returning arrays, such as this one:

```php
return [
'db' => [
'dsn' => 'mysql:...',
],
];
```

Wildcards are supported:

```php
use Zend\ConfigAggregator\ConfigAggregator;
use Zend\ConfigAggregator\PhpFileProvider;

$aggregator = new ConfigAggregator(
[
new PhpFileProvider('config/*.global.php'),
]
);
```

The example above will merge all matching files from the `config/` directory. If
you have files such as `app.global.php` or `database.global.php` in that
directory, they will be loaded using this above lines of code.

Globbing defaults to PHP's `glob()` function. However, if `Zend\Stdlib\Glob` is
available, it will use that to allow for cross-platform glob patterns, including
brace notation: `'config/autoload/{{,*.}global,{,*.}local}.php'`. Install
zendframework/zend-stdlib to utilize this feature.

### ZendConfigProvider

Sometimes using plain PHP files may be not enough; you may want to build your configuration
from multiple files of different formats, such as INI, YAML, or XML.
zend-config-aggregator allows you to do so via its `ZendConfigProvider`:
Together with `zend-config`, `zend-config-aggregator` can be also used to load configuration in different format - YAML, XML or INI:

```php
use Zend\ConfigAggregator\ConfigAggregator;
use Zend\ConfigAggregator\ZendConfigProvider;

$aggregator = new ConfigAggregator(
[
new ZendConfigProvider('*.global.json'),
new ZendConfigProvider('database.local.ini'),
]
);
$aggregator = new ConfigAggregator([
new ZendConfigProvider('config/*.{json,yaml,php}'),
]);
```

These could even be combined into a single glob statement:

```php
$aggregator = new ConfigAggregator(
[
new ZendConfigProvider('*.global.json,database.local.ini'),
]
);
```
For more details, please refer to the [documentation](https://zendframework.github.io/zend-config-aggregator/).

`ZendConfigProvider` accepts wildcards and autodetects the config type based on
file extension.
-----------------------------------------------------

ZendConfigProvider requires two packages to be installed:
`zendframework/zend-config` and `zendframework/zend-servicemanager`. Some config
readers (JSON, YAML) may need additional dependencies; please refer to
[the zend-config manual](https://docs.zendframework.com/zend-config/reader/)
for more details.
- File issues at https://github.com/zendframework/zend-config-aggregator/issues
- Documentation is at https://zendframework.github.io/zend-config-aggregator/
42 changes: 42 additions & 0 deletions doc/book/caching.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Caching

Merging configuration on every request is not performant. As such,
zend-config-aggregator also provides the ability to enable a filesystem-based
configuration cache.

To enable the configuration cache, pass a cache file name as the second
parameter to the `ConfigAggregator` constructor:

```php
$aggrgator = new ConfigAggregator(
[
function () { return [ConfigAggregator::ENABLE_CACHE => true]; },
new PhpFileProvider('*.global.php'),
],
'data/config-cache.php'
);
```

When a cache file is specified, you will also need to add the
`config_cache_enabled` key (which you can also specify via the
`ConfigAggregator::ENABLE_CACHE` constant) somewhere within one of your
configuration providers, and set it to boolean `true`. Using this approach, if
you were to use the globbing pattern `{{,*.}global,{,*.}local}.php` (or similar)
with the `PhpFileProvider`, you could drop a file named `enable-cache.local.php`
into your production deployment with the following contents in order to enable
configuration caching in production:

```php
<?php
use Zend\ConfigAggregator\ConfigAggregator;

return [
ConfigAggregator::ENABLE_CACHE => true,
];
```

When caching is enabled, the `ConfigAggregator` does not iterate config
providers. Because of that it is very fast, but after it is enabled you cannot
make any changes to configuration without clearing the cache. **Caching should
be used only in a production environment**, and your deployment process should
clear the cache.
Loading