|
1 | 1 | # zend-config-aggregator |
2 | 2 |
|
3 | | -[](https://travis-ci.org/zendframework/zend-config-aggregator) |
| 3 | +[](https://travis-ci.org/zendframework/zend-config-aggregator) |
4 | 4 |
|
5 | | -(Based on [mtymek/expressive-config-manager](https://github.com/mtymek/expressive-config-manager).) |
6 | | - |
7 | | -Lightweight library for collecting and merging configuration from different sources. |
8 | | - |
9 | | -While designed for [Expressive](https://github.com/zendframework/zend-expressive) |
10 | | -applications, it can work with any PHP project for aggregating and returning |
11 | | -merged configuration, from either a variety of configuration formats or |
12 | | -"configuration providers", invokable classes returning an array of configuration |
13 | | -(or a PHP generator). It also supports configuration caching. |
| 5 | +Aggregates and merges configuration, from a variety of formats. Supports caching |
| 6 | +for fast bootstrap in production environments. |
14 | 7 |
|
15 | 8 | ## Usage |
16 | 9 |
|
17 | | -### Config files |
18 | | - |
19 | | -At the basic level, `ConfigAggregator` can be used to merge PHP-based |
20 | | -configuration files: |
| 10 | +The standalone `ConfigAggregator` can be used to merge PHP-based configuration |
| 11 | +files: |
21 | 12 |
|
22 | 13 | ```php |
23 | 14 | use Zend\ConfigAggregator\ConfigAggregator; |
@@ -68,204 +59,21 @@ array(3) { |
68 | 59 | Configuration is merged in the same order as it is passed, with later entries |
69 | 60 | having precedence. |
70 | 61 |
|
71 | | -### Config providers |
72 | | - |
73 | | -`ConfigAggregator` works by aggregating "Config Providers" passed to its |
74 | | -constructor. Each provider should be a callable, returning a configuration |
75 | | -array (or a PHP generator) to be merged. |
76 | | - |
77 | | -```php |
78 | | -$aggregator = new ConfigAggregator([ |
79 | | - function () { |
80 | | - return ['foo' => 'bar']; |
81 | | - }, |
82 | | - new PhpFileProvider('*.global.php'), |
83 | | -]); |
84 | | -var_dump($aggregator->getMergedConfig()); |
85 | | -``` |
86 | | - |
87 | | -If the provider is a class name, the aggregator automatically instantiates it. |
88 | | -This can be used to mimic the Zend Framework module system: you can specify a |
89 | | -list of config providers from different packages, and aggregated configuration |
90 | | -will be available to your application. |
91 | | - |
92 | | -As a library owner, you can distribute your own configuration providers that |
93 | | -provide default values for use with your library. |
94 | | - |
95 | | -As an example: |
96 | | - |
97 | | -```php |
98 | | -class ApplicationConfig |
99 | | -{ |
100 | | - public function __invoke() |
101 | | - { |
102 | | - return ['foo' => 'bar']; |
103 | | - } |
104 | | -} |
105 | | - |
106 | | -$aggregator = new ConfigAggregator( |
107 | | - [ |
108 | | - ApplicationConfig::class, |
109 | | - new PhpFileProvider('*.global.php'), |
110 | | - ] |
111 | | -); |
112 | | -var_dump($configManager->getMergedConfig()); |
113 | | -``` |
114 | | - |
115 | | -Output from both examples will be the same: |
116 | | - |
117 | | -```php |
118 | | -array(4) { |
119 | | - 'foo' => |
120 | | - string(3) "bar" |
121 | | - 'db' => |
122 | | - array(1) { |
123 | | - 'dsn' => |
124 | | - string(9) "mysql:..." |
125 | | - } |
126 | | - 'cache_storage' => |
127 | | - string(5) "redis" |
128 | | - 'redis' => |
129 | | - array(0) { |
130 | | - } |
131 | | -} |
132 | | -``` |
133 | | - |
134 | | -### Caching |
135 | | - |
136 | | -Merging configuration on every request is not performant. As such, |
137 | | -zend-config-aggregator also provides the ability to enable a filesystem-based |
138 | | -configuration cache. |
139 | | - |
140 | | -To enable the configuration cache, pass a cache file name as the second |
141 | | -parameter to the `ConfigAggregator` constructor: |
142 | | - |
143 | | -```php |
144 | | -$aggrgator = new ConfigAggregator( |
145 | | - [ |
146 | | - function () { return [ConfigAggregator::ENABLE_CACHE => true]; }, |
147 | | - new PhpFileProvider('*.global.php'), |
148 | | - ], |
149 | | - 'data/config-cache.php' |
150 | | -); |
151 | | -``` |
152 | | - |
153 | | -When a cache file is specified, you will also need to add the |
154 | | -`config_cache_enabled` key (which you can also specify via the |
155 | | -`ConfigAggregator::ENABLE_CACHE` constant) somewhere within one of your |
156 | | -configuration providers, and set it to boolean `true`. Using this approach, if |
157 | | -you were to use the globbing pattern `{{,*.}global,{,*.}local}.php` (or similar) |
158 | | -with the `PhpFileProvider`, you could drop a file named `enable-cache.local.php` |
159 | | -into your production deployment with the following contents in order to enable |
160 | | -configuration caching in production: |
161 | | - |
162 | | -```php |
163 | | -<?php |
164 | | -use Zend\ConfigAggregator\ConfigAggregator; |
165 | | - |
166 | | -return [ |
167 | | - ConfigAggregator::ENABLE_CACHE => true, |
168 | | -]; |
169 | | -``` |
170 | | - |
171 | | -When caching is enabled, the `ConfigAggregator` does not iterate config |
172 | | -providers. Because of that it is very fast, but after it is enabled you cannot |
173 | | -make any changes to configuration without clearing the cache. **Caching should |
174 | | -be used only in a production environment**, and your deployment process should |
175 | | -clear the cache. |
176 | | - |
177 | | -### Generators |
178 | | - |
179 | | -Config providers can be written as generators. This way single callable can provide |
180 | | -multiple configurations: |
181 | | - |
182 | | -```php |
183 | | -use Zend\ConfigAggregator\ConfigAggregator; |
184 | | -use Zend\Stdlib\Glob; |
185 | | - |
186 | | -$aggregator = new ConfigAggregator([ |
187 | | - function () { |
188 | | - foreach (Glob::glob('data/*.global.php', Glob::GLOB_BRACE) as $file) { |
189 | | - yield include $file; |
190 | | - } |
191 | | - } |
192 | | -] |
193 | | -); |
194 | | -var_dump($aggregator->getMergedConfig()); |
195 | | -``` |
196 | | - |
197 | | -The providers `PhpFileProvider` is implemented using generators. |
198 | | - |
199 | | - |
200 | | -## Available config providers |
201 | | - |
202 | | -### PhpFileProvider |
203 | | - |
204 | | -Loads configuration from PHP files returning arrays, such as this one: |
205 | | - |
206 | | -```php |
207 | | -return [ |
208 | | - 'db' => [ |
209 | | - 'dsn' => 'mysql:...', |
210 | | - ], |
211 | | -]; |
212 | | -``` |
213 | | - |
214 | | -Wildcards are supported: |
215 | | - |
216 | | -```php |
217 | | -use Zend\ConfigAggregator\ConfigAggregator; |
218 | | -use Zend\ConfigAggregator\PhpFileProvider; |
219 | | - |
220 | | -$aggregator = new ConfigAggregator( |
221 | | - [ |
222 | | - new PhpFileProvider('config/*.global.php'), |
223 | | - ] |
224 | | -); |
225 | | -``` |
226 | | - |
227 | | -The example above will merge all matching files from the `config/` directory. If |
228 | | -you have files such as `app.global.php` or `database.global.php` in that |
229 | | -directory, they will be loaded using this above lines of code. |
230 | | - |
231 | | -Globbing defaults to PHP's `glob()` function. However, if `Zend\Stdlib\Glob` is |
232 | | -available, it will use that to allow for cross-platform glob patterns, including |
233 | | -brace notation: `'config/autoload/{{,*.}global,{,*.}local}.php'`. Install |
234 | | -zendframework/zend-stdlib to utilize this feature. |
235 | | - |
236 | | -### ZendConfigProvider |
237 | | - |
238 | | -Sometimes using plain PHP files may be not enough; you may want to build your configuration |
239 | | -from multiple files of different formats, such as INI, YAML, or XML. |
240 | | -zend-config-aggregator allows you to do so via its `ZendConfigProvider`: |
| 62 | +Together with `zend-config`, `zend-config-aggregator` can be also used to load |
| 63 | +configuration in different formats, including YAML, JSON, XML, or INI: |
241 | 64 |
|
242 | 65 | ```php |
243 | 66 | use Zend\ConfigAggregator\ConfigAggregator; |
244 | 67 | use Zend\ConfigAggregator\ZendConfigProvider; |
245 | 68 |
|
246 | | -$aggregator = new ConfigAggregator( |
247 | | - [ |
248 | | - new ZendConfigProvider('*.global.json'), |
249 | | - new ZendConfigProvider('database.local.ini'), |
250 | | - ] |
251 | | -); |
| 69 | +$aggregator = new ConfigAggregator([ |
| 70 | + new ZendConfigProvider('config/*.{json,yaml,php}'), |
| 71 | +]); |
252 | 72 | ``` |
253 | 73 |
|
254 | | -These could even be combined into a single glob statement: |
255 | | - |
256 | | -```php |
257 | | -$aggregator = new ConfigAggregator( |
258 | | - [ |
259 | | - new ZendConfigProvider('*.global.json,database.local.ini'), |
260 | | - ] |
261 | | -); |
262 | | -``` |
| 74 | +For more details, please refer to the [documentation](https://docs.zendframework.com/zend-config-aggregator/). |
263 | 75 |
|
264 | | -`ZendConfigProvider` accepts wildcards and autodetects the config type based on |
265 | | -file extension. |
| 76 | +----- |
266 | 77 |
|
267 | | -ZendConfigProvider requires two packages to be installed: |
268 | | -`zendframework/zend-config` and `zendframework/zend-servicemanager`. Some config |
269 | | -readers (JSON, YAML) may need additional dependencies; please refer to |
270 | | -[the zend-config manual](https://docs.zendframework.com/zend-config/reader/) |
271 | | -for more details. |
| 78 | +- File issues at https://github.com/zendframework/zend-config-aggregator/issues |
| 79 | +- Documentation is at https://docs.zendframework.com/zend-config-aggregator/ |
0 commit comments