Skip to content

Commit d861be3

Browse files
javiereguiluzjaviereguiluz
committed
Added all the suggestions made by reviewers
1 parent 0520bf1 commit d861be3

File tree

2 files changed

+216
-48
lines changed

2 files changed

+216
-48
lines changed

‎cookbook/configuration/configuration_organization.rst‎

Lines changed: 215 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
.. index::
2-
single: Configuration, Environments
2+
single: Configuration
33

44
How to Organize Configuration Files
55
===================================
@@ -47,7 +47,7 @@ default Symfony Standard Edition follow this structure:
4747
├─ vendor/
4848
└─ web/
4949
50-
This default structure was choosen for its simplicity — one file per environment.
50+
This default structure was chosen for its simplicity — one file per environment.
5151
But as any other Symfony feature, you can customize it to better suit your needs.
5252
The following sections explain different ways to organize your configuration
5353
files. In order to simplify the examples, only the ``dev`` and ``prod``
@@ -101,38 +101,104 @@ method::
101101
Then, make sure that each ``config.yml`` file loads the rest of the configuration
102102
files, including the common files:
103103

104-
.. code-block:: yaml
104+
.. configuration-block::
105105

106-
# app/config/dev/config.yml
107-
imports:
108-
- { resource: '../config.yml' }
109-
- { resource: 'parameters.yml' }
110-
- { resource: 'security.yml' }
106+
.. code-block:: yaml
111107
112-
# ...
108+
# app/config/dev/config.yml
109+
imports:
110+
- { resource: '../common/config.yml' }
111+
- { resource: 'parameters.yml' }
112+
- { resource: 'security.yml' }
113113
114-
# app/config/prod/config.yml
115-
imports:
116-
- { resource: '../config.yml' }
117-
- { resource: 'parameters.yml' }
118-
- { resource: 'security.yml' }
114+
# ...
119115
120-
# ...
116+
.. code-block:: xml
121117
118+
<!-- # app/config/dev/config.xml -->
119+
<imports>
120+
<import resource="../common/config.xml" />
121+
<import resource="parameters.xml" />
122+
<import resource="security.xml" />
123+
</imports>
122124
123-
# app/config/common/config.yml
124-
imports:
125-
- { resource: 'parameters.yml' }
126-
- { resource: 'security.yml' }
125+
<!-- ... -->
127126
128-
# ...
127+
.. code-block:: php
129128
129+
// app/config/dev/config.php
130+
$loader->import('../common/config.php');
131+
$loader->import('parameters.php');
132+
$loader->import('security.php');
133+
134+
// ...
135+
136+
.. configuration-block::
137+
138+
.. code-block:: yaml
139+
140+
# app/config/prod/config.yml
141+
imports:
142+
- { resource: '../common/config.yml' }
143+
- { resource: 'parameters.yml' }
144+
- { resource: 'security.yml' }
145+
146+
# ...
147+
148+
.. code-block:: xml
149+
150+
<!-- # app/config/prod/config.xml -->
151+
<imports>
152+
<import resource="../common/config.xml" />
153+
<import resource="parameters.xml" />
154+
<import resource="security.xml" />
155+
</imports>
156+
157+
<!-- ... -->
158+
159+
.. code-block:: php
160+
161+
// app/config/prod/config.php
162+
$loader->import('../common/config.php');
163+
$loader->import('parameters.php');
164+
$loader->import('security.php');
165+
166+
// ...
167+
168+
.. configuration-block::
169+
170+
.. code-block:: yaml
171+
172+
# app/config/config.yml
173+
imports:
174+
- { resource: 'parameters.yml' }
175+
- { resource: 'security.yml' }
176+
177+
# ...
178+
179+
.. code-block:: xml
180+
181+
<!-- # app/config/config.xml -->
182+
<imports>
183+
<import resource="parameters.xml" />
184+
<import resource="security.xml" />
185+
</imports>
186+
187+
<!-- ... -->
188+
189+
.. code-block:: php
190+
191+
// app/config/config.php
192+
$loader->import('parameters.php');
193+
$loader->import('security.php');
194+
195+
// ...
130196
131197
Semantic Configuration Files
132198
----------------------------
133199

134200
A different organization strategy may be needed for complex applications with
135-
large configuration files. You could for instance create one file per bundle
201+
large configuration files. For instance, you could create one file per bundle
136202
and several files to define all the application services:
137203

138204
.. code-block:: text
@@ -176,6 +242,10 @@ make Symfony aware of the new file organization::
176242
}
177243
}
178244

245+
Following the same technique explained in the previous section, make sure to
246+
load the appropriate configuration files from each main file (``common.yml``,
247+
``dev.yml`` and ``prod.yml``).
248+
179249
Advanced Tecniques
180250
------------------
181251

@@ -188,19 +258,50 @@ Mix and Match Configuration Formats
188258
Configuration files can import files defined with any other built-in configuration
189259
format (``.yml``, ``.xml``, ``.php``, ``.ini``):
190260

191-
.. code-block:: yaml
261+
.. configuration-block::
262+
263+
.. code-block:: yaml
264+
265+
# app/config/config.yml
266+
imports:
267+
- { resource: 'parameters.yml' }
268+
- { resource: 'services.xml' }
269+
- { resource: 'security.yml' }
270+
- { resource: 'legacy.php' }
271+
272+
# ...
273+
274+
.. code-block:: xml
275+
276+
<!-- # app/config/config.xml -->
277+
<imports>
278+
<import resource="parameters.yml" />
279+
<import resource="services.xml" />
280+
<import resource="security.yml" />
281+
<import resource="legacy.php" />
282+
</imports>
283+
284+
<!-- ... -->
192285
193-
# app/config/config.yml
194-
imports:
195-
- { resource: 'parameters.yml' }
196-
- { resource: 'services.xml' }
197-
- { resource: 'security.yml' }
198-
- { resource: 'legacy.php' }
286+
.. code-block:: php
199287
200-
# ...
288+
// app/config/config.php
289+
$loader->import('parameters.yml');
290+
$loader->import('services.xml');
291+
$loader->import('security.yml');
292+
$loader->import('legacy.php');
293+
294+
// ...
295+
296+
.. caution::
297+
298+
The ``IniFileLoader`` parses the file contents using the
299+
:phpfunction:`parse_ini_file` function, therefore, you can only set
300+
parameters to string values. To set parameters to other data types
301+
(e.g. boolean, integer, etc), the other loaders are recommended.
201302

202303
If you use any other configuration format, you have to define your own loader
203-
class extending it from ``Symfony\Component\DependencyInjection\Loader\FileLoader``.
304+
class extending it from :class:`Symfony\\Component\\DependencyInjection\\Loader\\FileLoader`.
204305
When the configuration values are dynamic, you can use the PHP configuration
205306
file to execute your own logic. In addition, you can define your own services
206307
to load configuration from databases and web services.
@@ -212,14 +313,35 @@ Splitting configuration into lots of smaller files can rapidly become cumbersome
212313
when importing those files from the main configuration file. Avoid these problems
213314
by loading an entire directory:
214315

215-
.. code-block:: yaml
316+
.. configuration-block::
317+
318+
.. code-block:: yaml
319+
320+
# app/config/config.yml
321+
imports:
322+
- { resource: 'bundles/' }
323+
- { resource: 'services/' }
324+
325+
# ...
326+
327+
.. code-block:: xml
216328
217-
# app/config/config.yml
218-
imports:
219-
- { resource: 'bundles/' }
220-
- { resource: 'services/' }
329+
<!-- # app/config/config.xml -->
330+
<imports>
331+
<import resource="bundles/" />
332+
<import resource="services/" />
333+
</imports>
334+
335+
<!-- ... -->
336+
337+
.. code-block:: php
338+
339+
// app/config/config.php
340+
$loader->import('bundles/');
341+
$loader->import('services/');
342+
343+
// ...
221344
222-
# ...
223345
224346
The Config component will look for recursively in the ``bundles/`` and ``services/``
225347
directories and it will load any supported file format (``.yml``, ``.xml``,
@@ -234,25 +356,70 @@ credentials for your website are stored in the ``/etc/sites/mysite.com/parameter
234356
Loading this file is as simple as indicating the full file path when importing
235357
it from any other configuration file:
236358

237-
.. code-block:: yaml
359+
.. configuration-block::
360+
361+
.. code-block:: yaml
362+
363+
# app/config/config.yml
364+
imports:
365+
- { resource: 'parameters.yml' }
366+
- { resource: '/etc/sites/mysite.com/parameters.yml' }
238367
239-
# app/config/config.yml
240-
imports:
241-
- { resource: 'parameters.yml' }
242-
- { resource: '/etc/sites/mysite.com/parameters.yml' }
368+
# ...
243369
244-
# ...
370+
.. code-block:: xml
371+
372+
<!-- # app/config/config.xml -->
373+
<imports>
374+
<import resource="parameters.yml" />
375+
<import resource="/etc/sites/mysite.com/parameters.yml" />
376+
</imports>
377+
378+
<!-- ... -->
379+
380+
.. code-block:: php
381+
382+
// app/config/config.php
383+
$loader->import('parameters.yml');
384+
$loader->import('/etc/sites/mysite.com/parameters.yml');
385+
386+
// ...
245387
246388
Most of the time, local developers won't have the same files that exist in the
247389
production servers. For that reason, the Config component provides the
248390
``ignore_errors`` option to silently discard errors when the loaded file
249391
doesn't exist:
250392

251-
.. code-block:: yaml
393+
.. configuration-block::
394+
395+
.. code-block:: yaml
396+
397+
# app/config/config.yml
398+
imports:
399+
- { resource: 'parameters.yml' }
400+
- { resource: '/etc/sites/mysite.com/parameters.yml', ignore_errors: true }
252401
253-
# app/config/config.yml
254-
imports:
255-
- { resource: 'parameters.yml' }
256-
- { resource: '/etc/sites/mysite.com/parameters.yml', ignore_errors: true }
402+
# ...
403+
404+
.. code-block:: xml
405+
406+
<!-- # app/config/config.xml -->
407+
<imports>
408+
<import resource="parameters.yml" />
409+
<import resource="/etc/sites/mysite.com/parameters.yml" ignore-errors="true" />
410+
</imports>
411+
412+
<!-- ... -->
413+
414+
.. code-block:: php
415+
416+
// app/config/config.php
417+
$loader->import('parameters.yml');
418+
$loader->import('/etc/sites/mysite.com/parameters.yml', null, true);
419+
420+
// ...
257421
258-
# ...
422+
As you've seen, there are lots of ways to organize your configuration files. You
423+
can choose one of these or even create your own custom way of organizing the
424+
files. Don't feel limited by the standard edition that comes with Symfony. For even
425+
more customization, see ":doc:`dir_structure`".

‎cookbook/map.rst.inc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
* :doc:`/cookbook/configuration/pdo_session_storage`
3131
* :doc:`/cookbook/configuration/apache_router`
3232
* :doc:`/cookbook/configuration/web_server_configuration`
33+
* :doc:`/cookbook/configuration/configuration_organization`
3334

3435
* :doc:`/cookbook/console/index`
3536

0 commit comments

Comments
 (0)