Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit df0cf68

Browse files
weaverryanweaverryan
committed
feature #3885 [RFR] Added "How to Organize Configuration Files" cookbook (javiereguiluz)
This PR was merged into the 2.3 branch. Discussion ---------- [RFR] Added "How to Organize Configuration Files" cookbook | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | 2.3+ | Fixed tickets | #3680 This is just the first draft of a new cookbook. Please, tell me anything that I should add, change or remove. Thanks! Commits ------- 4241ee5 Removed redundant configuration blocks 68a7d2a Added more suggestions made by @xabbuh be414e0 Removed the "Directory Loading" section because it doesn't work out of the box da3e1d0 Fixed the target of one cookbook article link af5d478 Added suggestions made by @cordoval 4a87cfb Fixed the link to another cookbook article 2a32b23 Added the latest suggestions made by reviewers d861be3 Added all the suggestions made by reviewers 0520bf1 Firest draft of the "How to Organize Configuration Files" cookbook
2 parents 7bb4f34 + 4241ee5 commit df0cf68

File tree

3 files changed

+365
-0
lines changed

3 files changed

+365
-0
lines changed

‎cookbook/configuration/configuration_organization.rst

Lines changed: 363 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,363 @@
1+
.. index::
2+
single: Configuration
3+
4+
How to Organize Configuration Files
5+
===================================
6+
7+
The default Symfony2 Standard Edition defines three
8+
:doc:`execution environments </cookbook/configuration/environments>` called
9+
``dev``, ``prod`` and ``test``. An environment simply represents a way to
10+
execute the same codebase with different configurations.
11+
12+
In order to select the configuration file to load for each environment, Symfony
13+
executes the ``registerContainerConfiguration()`` method of the ``AppKernel``
14+
class::
15+
16+
// app/AppKernel.php
17+
use Symfony\Component\HttpKernel\Kernel;
18+
use Symfony\Component\Config\Loader\LoaderInterface;
19+
20+
class AppKernel extends Kernel
21+
{
22+
// ...
23+
24+
public function registerContainerConfiguration(LoaderInterface $loader)
25+
{
26+
$loader->load(__DIR__.'/config/config_'.$this->getEnvironment().'.yml');
27+
}
28+
}
29+
30+
This method loads the ``app/config/config_dev.yml`` file for the ``dev``
31+
environment and so on. In turn, this file loads the common configuration file
32+
located at ``app/config/config.yml``. Therefore, the configuration files of the
33+
default Symfony Standard Edition follow this structure:
34+
35+
.. code-block:: text
36+
37+
<your-project>/
38+
├─ app/
39+
│ └─ config/
40+
│ ├─ config.yml
41+
│ ├─ config_dev.yml
42+
│ ├─ config_prod.yml
43+
│ ├─ config_test.yml
44+
│ ├─ parameters.yml
45+
│ ├─ parameters.yml.dist
46+
│ ├─ routing.yml
47+
│ ├─ routing_dev.yml
48+
│ └─ security.yml
49+
├─ src/
50+
├─ vendor/
51+
└─ web/
52+
53+
This default structure was chosen for its simplicity — one file per environment.
54+
But as any other Symfony feature, you can customize it to better suit your needs.
55+
The following sections explain different ways to organize your configuration
56+
files. In order to simplify the examples, only the ``dev`` and ``prod``
57+
environments are taken into account.
58+
59+
Different Directories per Environment
60+
-------------------------------------
61+
62+
Instead of suffixing the files with ``_dev`` and ``_prod``, this technique
63+
groups all the related configuration files under a directory with the same
64+
name as the environment:
65+
66+
.. code-block:: text
67+
68+
<your-project>/
69+
├─ app/
70+
│ └─ config/
71+
│ ├─ common/
72+
│ │ ├─ config.yml
73+
│ │ ├─ parameters.yml
74+
│ │ ├─ routing.yml
75+
│ │ └─ security.yml
76+
│ ├─ dev/
77+
│ │ ├─ config.yml
78+
│ │ ├─ parameters.yml
79+
│ │ ├─ routing.yml
80+
│ │ └─ security.yml
81+
│ └─ prod/
82+
│ ├─ config.yml
83+
│ ├─ parameters.yml
84+
│ ├─ routing.yml
85+
│ └─ security.yml
86+
├─ src/
87+
├─ vendor/
88+
└─ web/
89+
90+
To make this work, change the code of the
91+
:method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration`
92+
method::
93+
94+
// app/AppKernel.php
95+
use Symfony\Component\HttpKernel\Kernel;
96+
use Symfony\Component\Config\Loader\LoaderInterface;
97+
98+
class AppKernel extends Kernel
99+
{
100+
// ...
101+
102+
public function registerContainerConfiguration(LoaderInterface $loader)
103+
{
104+
$loader->load(__DIR__.'/config/'.$this->getEnvironment().'/config.yml');
105+
}
106+
}
107+
108+
Then, make sure that each ``config.yml`` file loads the rest of the configuration
109+
files, including the common files. For instance, this would be the imports
110+
needed for the ``app/config/dev/config.yml`` file:
111+
112+
.. configuration-block::
113+
114+
.. code-block:: yaml
115+
116+
# app/config/dev/config.yml
117+
imports:
118+
- { resource: '../common/config.yml' }
119+
- { resource: 'parameters.yml' }
120+
- { resource: 'security.yml' }
121+
122+
# ...
123+
124+
.. code-block:: xml
125+
126+
<!-- app/config/dev/config.xml -->
127+
<?xml version="1.0" encoding="UTF-8" ?>
128+
<container xmlns="http://symfony.com/schema/dic/services"
129+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
130+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
131+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
132+
133+
<imports>
134+
<import resource="../common/config.xml" />
135+
<import resource="parameters.xml" />
136+
<import resource="security.xml" />
137+
</imports>
138+
139+
<!-- ... -->
140+
</container>
141+
142+
.. code-block:: php
143+
144+
// app/config/dev/config.php
145+
$loader->import('../common/config.php');
146+
$loader->import('parameters.php');
147+
$loader->import('security.php');
148+
149+
// ...
150+
151+
Semantic Configuration Files
152+
----------------------------
153+
154+
A different organization strategy may be needed for complex applications with
155+
large configuration files. For instance, you could create one file per bundle
156+
and several files to define all application services:
157+
158+
.. code-block:: text
159+
160+
<your-project>/
161+
├─ app/
162+
│ └─ config/
163+
│ ├─ bundles/
164+
│ │ ├─ bundle1.yml
165+
│ │ ├─ bundle2.yml
166+
│ │ ├─ ...
167+
│ │ └─ bundleN.yml
168+
│ ├─ environments/
169+
│ │ ├─ common.yml
170+
│ │ ├─ dev.yml
171+
│ │ └─ prod.yml
172+
│ ├─ routing/
173+
│ │ ├─ common.yml
174+
│ │ ├─ dev.yml
175+
│ │ └─ prod.yml
176+
│ └─ services/
177+
│ ├─ frontend.yml
178+
│ ├─ backend.yml
179+
│ ├─ ...
180+
│ └─ security.yml
181+
├─ src/
182+
├─ vendor/
183+
└─ web/
184+
185+
Again, change the code of the ``registerContainerConfiguration()`` method to
186+
make Symfony aware of the new file organization::
187+
188+
// app/AppKernel.php
189+
use Symfony\Component\HttpKernel\Kernel;
190+
use Symfony\Component\Config\Loader\LoaderInterface;
191+
192+
class AppKernel extends Kernel
193+
{
194+
// ...
195+
196+
public function registerContainerConfiguration(LoaderInterface $loader)
197+
{
198+
$loader->load(__DIR__.'/config/environments/'.$this->getEnvironment().'.yml');
199+
}
200+
}
201+
202+
Following the same technique explained in the previous section, make sure to
203+
import the appropriate configuration files from each main file (``common.yml``,
204+
``dev.yml`` and ``prod.yml``).
205+
206+
Advanced Techniques
207+
-------------------
208+
209+
Symfony loads configuration files using the
210+
:doc:`Config component </components/config/introduction>`, which provides some
211+
advanced features.
212+
213+
Mix and Match Configuration Formats
214+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215+
216+
Configuration files can import files defined with any other built-in configuration
217+
format (``.yml``, ``.xml``, ``.php``, ``.ini``):
218+
219+
.. configuration-block::
220+
221+
.. code-block:: yaml
222+
223+
# app/config/config.yml
224+
imports:
225+
- { resource: 'parameters.yml' }
226+
- { resource: 'services.xml' }
227+
- { resource: 'security.yml' }
228+
- { resource: 'legacy.php' }
229+
230+
# ...
231+
232+
.. code-block:: xml
233+
234+
<!-- app/config/config.xml -->
235+
<?xml version="1.0" encoding="UTF-8" ?>
236+
<container xmlns="http://symfony.com/schema/dic/services"
237+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
238+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
239+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
240+
241+
<imports>
242+
<import resource="parameters.yml" />
243+
<import resource="services.xml" />
244+
<import resource="security.yml" />
245+
<import resource="legacy.php" />
246+
</imports>
247+
248+
<!-- ... -->
249+
</container>
250+
251+
.. code-block:: php
252+
253+
// app/config/config.php
254+
$loader->import('parameters.yml');
255+
$loader->import('services.xml');
256+
$loader->import('security.yml');
257+
$loader->import('legacy.php');
258+
259+
// ...
260+
261+
.. caution::
262+
263+
The ``IniFileLoader`` parses the file contents using the
264+
:phpfunction:`parse_ini_file` function. Therefore, you can only set
265+
parameters to string values. Use one of the other loaders if you want
266+
to use other data types (e.g. boolean, integer, etc.).
267+
268+
If you use any other configuration format, you have to define your own loader
269+
class extending it from :class:`Symfony\\Component\\DependencyInjection\\Loader\\FileLoader`.
270+
When the configuration values are dynamic, you can use the PHP configuration
271+
file to execute your own logic. In addition, you can define your own services
272+
to load configurations from databases or web services.
273+
274+
Global Configuration Files
275+
~~~~~~~~~~~~~~~~~~~~~~~~~~
276+
277+
Some system administrators may prefer to store sensitive parameters in files
278+
outside the project directory. Imagine that the database credentials for your
279+
website are stored in the ``/etc/sites/mysite.com/parameters.yml`` file. Loading
280+
this file is as simple as indicating the full file path when importing it from
281+
any other configuration file:
282+
283+
.. configuration-block::
284+
285+
.. code-block:: yaml
286+
287+
# app/config/config.yml
288+
imports:
289+
- { resource: 'parameters.yml' }
290+
- { resource: '/etc/sites/mysite.com/parameters.yml' }
291+
292+
# ...
293+
294+
.. code-block:: xml
295+
296+
<!-- app/config/config.xml -->
297+
<?xml version="1.0" encoding="UTF-8" ?>
298+
<container xmlns="http://symfony.com/schema/dic/services"
299+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
300+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
301+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
302+
303+
<imports>
304+
<import resource="parameters.yml" />
305+
<import resource="/etc/sites/mysite.com/parameters.yml" />
306+
</imports>
307+
308+
<!-- ... -->
309+
</container>
310+
311+
.. code-block:: php
312+
313+
// app/config/config.php
314+
$loader->import('parameters.yml');
315+
$loader->import('/etc/sites/mysite.com/parameters.yml');
316+
317+
// ...
318+
319+
Most of the time, local developers won't have the same files that exist on the
320+
production servers. For that reason, the Config component provides the
321+
``ignore_errors`` option to silently discard errors when the loaded file
322+
doesn't exist:
323+
324+
.. configuration-block::
325+
326+
.. code-block:: yaml
327+
328+
# app/config/config.yml
329+
imports:
330+
- { resource: 'parameters.yml' }
331+
- { resource: '/etc/sites/mysite.com/parameters.yml', ignore_errors: true }
332+
333+
# ...
334+
335+
.. code-block:: xml
336+
337+
<!-- app/config/config.xml -->
338+
<?xml version="1.0" encoding="UTF-8" ?>
339+
<container xmlns="http://symfony.com/schema/dic/services"
340+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
341+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
342+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
343+
344+
<imports>
345+
<import resource="parameters.yml" />
346+
<import resource="/etc/sites/mysite.com/parameters.yml" ignore-errors="true" />
347+
</imports>
348+
349+
<!-- ... -->
350+
</container>
351+
352+
.. code-block:: php
353+
354+
// app/config/config.php
355+
$loader->import('parameters.yml');
356+
$loader->import('/etc/sites/mysite.com/parameters.yml', null, true);
357+
358+
// ...
359+
360+
As you've seen, there are lots of ways to organize your configuration files. You
361+
can choose one of these or even create your own custom way of organizing the
362+
files. Don't feel limited by the Standard Edition that comes with Symfony. For even
363+
more customization, see ":doc:`/cookbook/configuration/override_dir_structure`".

‎cookbook/configuration/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,4 @@ Configuration
1212
pdo_session_storage
1313
apache_router
1414
web_server_configuration
15+
configuration_organization

‎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)