8000 minor #8732 Updated the configuration/* files (javiereguiluz) · symfony/symfony-docs@79074e1 · GitHub
[go: up one dir, main page]
Skip to content

Commit 79074e1

Browse files
weaverryanweaverryan
committed
minor #8732 Updated the configuration/* files (javiereguiluz)
This PR was squashed before being merged into the 4.0 branch (closes #8732). Discussion ---------- Updated the configuration/* files This fixes #8725 and required a ton of changes. Besides, I don't really like the config/* articles at all. I'll try to improve things after Symfony 4 release. Thanks! Commits ------- 6aabd10 Removed links to specific files (they are not easy to maintain) 0684c4a Updated the configuration/* files
2 parents 5d4b335 + 6aabd10 commit 79074e1

7 files changed

+261
-565
lines changed

‎configuration/configuration_organization.rst

Lines changed: 57 additions & 246 deletions
Original file line numberDiff line numberDiff line change
@@ -9,199 +9,63 @@ called ``dev``, ``prod`` and ``test``. An environment simply represents a way
99
to execute the same codebase with different configurations.
1010

1111
In order to select the configuration file to load for each environment, Symfony
12-
executes the ``registerContainerConfiguration()`` method of the ``AppKernel``
13-
class::
12+
executes the ``configureContainer()`` method of the ``Kernel`` class::
1413

15-
// app/AppKernel.php
16-
use Symfony\Component\HttpKernel\Kernel;
14+
// src/Kernel.php
1715
use Symfony\Component\Config\Loader\LoaderInterface;
16+
use Symfony\Component\DependencyInjection\ContainerBuilder;
17+
use Symfony\Component\HttpKernel\Kernel as BaseKernel;
1818

1919
class Kernel extends BaseKernel
2020
{
21-
// ...
22-
23-
public function registerContainerConfiguration(LoaderInterface $loader)
24-
{
25-
$loader->load($this->getProjectDir().'/app/config/config_'.$this->getEnvironment().'.yml');
26-
}
27-
}
28-
29-
This method loads the ``app/config/config_dev.yml`` file for the ``dev``
30-
environment and so on. In turn, this file loads the common configuration file
31-
located at ``app/config/config.yml``. Therefore, the configuration files of the
32-
default Symfony Standard Edition follow this structure:
33-
34-
.. code-block:: text
35-
36-
your-project/
37-
├─ app/
38-
│ ├─ ...
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-
├─ ...
50-
51-
This default structure was chosen for its simplicity — one file per environment.
52-
But as any other Symfony feature, you can customize it to better suit your needs.
53-
The following sections explain different ways to organize your configuration
54-
files. In order to simplify the examples, only the ``dev`` and ``prod``
55-
environments are taken into account.
21+
const CONFIG_EXTS = '.{php,xml,yaml,yml}';
5622

57-
Different Directories per Environment
58-
-------------------------------------
59-
60-
Instead of suffixing the files with ``_dev`` and ``_prod``, this technique
61-
groups all the related configuration files under a directory with the same
62-
name as the environment:
63-
64-
.. code-block:: text
65 1E79 -
66-
your-project/
67-
├─ app/
68-
│ ├─ ...
69-
│ └─ config/
70-
│ ├─ common/
71-
│ │ ├─ config.yml
72-
│ │ ├─ parameters.yml
73-
│ │ ├─ routing.yml
74-
│ │ └─ security.yml
75-
│ ├─ dev/
76-
│ │ ├─ config.yml
77-
│ │ ├─ parameters.yml
78-
│ │ ├─ routing.yml
79-
│ │ └─ security.yml
80-
│ └─ prod/
81-
│ ├─ config.yml
82-
│ ├─ parameters.yml
83-
│ ├─ routing.yml
84-
│ └─ security.yml
85-
├─ ...
86-
87-
To make this work, change the code of the
88-
:method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration`
89-
method::
90-
91-
// app/AppKernel.php
92-
use Symfony\Component\HttpKernel\Kernel;
93-
use Symfony\Component\Config\Loader\LoaderInterface;
94-
95-
class AppKernel extends Kernel
96-
{
9723
// ...
9824

99-
public function registerContainerConfiguration(LoaderInterface $loader)
25+
public function configureContainer(ContainerBuilder $container, LoaderInterface $loader)
10026
{
101-
$loader->load($this->getProjectDir().'/app/config/'.$this->getEnvironment().'/config.yml');
27+
$confDir = $this->getProjectDir().'/config';
28+
$loader->load($confDir.'/packages/*'.self::CONFIG_EXTS, 'glob');
29+
if (is_dir($confDir.'/packages/'.$this->environment)) {
30+
$loader->load($confDir.'/packages/'.$this->environment.'/**/*'.self::CONFIG_EXTS, 'glob');
31+
}
32+
$loader->load($confDir.'/services'.self::CONFIG_EXTS, 'glob');
33+
$loader->load($confDir.'/services_'.$this->environment.self::CONFIG_EXTS, 'glob');
10234
}
10335
}
10436

105-
Then, make sure that each ``config.yml`` file loads the rest of the configuration
106-
files, including the common files. For instance, this would be the imports
107-
needed for the ``app/config/dev/config.yml`` file:
37+
For the ``dev`` environment, Symfony loads the following config files and
38+
directories and in this order:
10839

109-
.. configuration-block::
110-
111-
.. code-block:: yaml
112-
113-
# app/config/dev/config.yml
114-
imports:
115-
- { resource: '../common/config.yml' }
116-
- { resource: 'parameters.yml' }
117-
- { resource: 'security.yml' }
118-
119-
# ...
120-
121-
.. code-block:: xml
122-
123-
<!-- app/config/dev/config.xml -->
124-
<?xml version="1.0" encoding="UTF-8" ?>
125-
<container xmlns="http://symfony.com/schema/dic/services"
126-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
127-
xsi:schemaLocation="http://symfony.com/schema/dic/services
128-
http://symfony.com/schema/dic/services/services-1.0.xsd
129-
http://symfony.com/schema/dic/symfony
130-
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
131-
132-
<imports>
133-
<import resource="../common/config.xml" />
134-
<import resource="parameters.xml" />
135-
<import resource="security.xml" />
136-
</imports>
137-
138-
<!-- ... -->
139-
</container>
40+
#. ``config/packages/*``
41+
#. ``config/packages/dev/*``
42+
#. ``config/services.yaml``
43+
#. ``config/services_dev.yaml``
14044

141-
.. code-block:: php
142-
143-
// app/config/dev/config.php
144-
$loader->import('../common/config.php');
145-
$loader->import('parameters.php');
146-
$loader->import('security.php');
147-
148-
// ...
149-
150-
.. include:: /components/dependency_injection/_imports-parameters-note.rst.inc
151-
152-
Semantic Configuration Files
153-
----------------------------
154-
155-
A different organization strategy may be needed for complex applications with
156-
large configuration files. For instance, you could create one file per bundle
157-
and several files to define all application services:
45+
Therefore, the configuration files of the default Symfony applications follow
46+
this structure:
15847

15948
.. code-block:: text
16049
16150
your-project/
162-
├─ app/
163-
│ ├─ ...
164-
│ └─ config/
165-
│ ├─ bundles/
166-
│ │ ├─ bundle1.yml
167-
│ │ ├─ bundle2.yml
168-
│ │ ├─ ...
169-
│ │ └─ bundleN.yml
170-
│ ├─ environments/
171-
│ │ ├─ common.yml
172-
│ │ ├─ dev.yml
173-
│ │ └─ prod.yml
174-
│ ├─ routing/
175-
│ │ ├─ common.yml
176-
│ │ ├─ dev.yml
177-
│ │ └─ prod.yml
178-
│ └─ services/
179-
│ ├─ frontend.yml
180-
│ ├─ backend.yml
181-
│ ├─ ...
182-
│ └─ security.yml
51+
├─ config/
52+
│ └─ packages/
53+
│ ├─ dev/
54+
| │ ├─ framework.yaml
55+
│ │ └─ ...
56+
│ ├─ prod/
57+
│ │ └─ ...
58+
│ ├─ test/
59+
│ │ └─ ...
60+
| ├─ framework.yaml
61+
│ └─ ...
62+
│ ├─ services.yaml
63+
│ └─ services_dev.yaml
18364
├─ ...
18465
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($this->getProjectDir().'/app/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``).
66+
This default structure was chosen for its simplicity — one file per package and
67+
environment. But as any other Symfony feature, you can customize it to better
68+
suit your needs.
20569

20670
Advanced Techniques
20771
-------------------
@@ -220,18 +84,16 @@ format (``.yml``, ``.xml``, ``.php``, ``.ini``):
22084

22185
.. code-block:: yaml
22286
223-
# app/config/config.yml
87+
# config/services.yaml
22488
imports:
225-
- { resource: 'parameters.yml' }
226-
- { resource: 'services.xml' }
227-
- { resource: 'security.yml' }
89+
- { resource: 'my_config_file.xml' }
22890
- { resource: 'legacy.php' }
22991
23092
# ...
23193
23294
.. code-block:: xml
23395
234-
<!-- app/config/config.xml -->
96+
<!-- config/services.xml -->
23597
<?xml version="1.0" encoding="UTF-8" ?>
23698
<container xmlns="http://symfony.com/schema/dic/services"
23799
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -241,9 +103,7 @@ format (``.yml``, ``.xml``, ``.php``, ``.ini``):
241103
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
242104
243105
<imports>
244-
<import resource="parameters.yml" />
245-
<import resource="services.xml" />
246-
<import resource="security.yml" />
106+
<import resource="my_config_file.yaml" />
247107
<import resource="legacy.php" />
248108
</imports>
249109
@@ -252,21 +112,12 @@ format (``.yml``, ``.xml``, ``.php``, ``.ini``):
252112
253113
.. code-block:: php
254114
255-
// app/config/config.php
256-
$loader->import('parameters.yml');
257-
$loader->import('services.xml');
258-
$loader->import('security.yml');
259-
$loader->import('legacy.php');
115+
// config/services.php
116+
$loader->import('my_config_file.yaml');
117+
$loader->import('legacy.xml');
260118
261119
// ...
262120
263-
.. caution::
264-
265-
The ``IniFileLoader`` parses the file contents using the
266-
:phpfunction:`parse_ini_file` function. Therefore, you can only set
267-
parameters to string values. Use one of the other loaders if you want
268-
to use other data types (e.g. boolean, integer, etc.).
269-
270121
If you use any other configuration format, you have to define your own loader
271122
class extending it from :class:`Symfony\\Component\\DependencyInjection\\Loader\\FileLoader`.
272123
When the configuration values are dynamic, you can use the PHP configuration
@@ -278,24 +129,23 @@ Global Configuration Files
278129

279130
Some system administrators may prefer to store sensitive parameters in files
280131
outside the project directory. Imagine that the database credentials for your
281-
website are stored in the ``/etc/sites/mysite.com/parameters.yml`` file. Loading
132+
website are stored in the ``/etc/sites/mysite.com/parameters.yaml`` file. Loading
282133
this file is as simple as indicating the full file path when importing it from
283134
any other configuration file:
284135

285136
.. configuration-block::
286137

287138
.. code-block:: yaml
288139
289-
# app/config/config.yml
140+
# config/services.yaml
290141
imports:
291-
- { resource: 'parameters.yml' }
292-
- { resource: '/etc/sites/mysite.com/parameters.yml' }
142+
- { resource: '/etc/sites/mysite.com/parameters.yaml', ignore_errors: true }
293143
294144
# ...
295145
296146
.. code-block:: xml
297147
298-
<!-- app/config/config.xml -->
148+
<!-- config/services.xml -->
299149
<?xml version="1.0" encoding="UTF-8" ?>
300150
<container xmlns="http://symfony.com/schema/dic/services"
301151
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -305,65 +155,26 @@ any other configuration file:
305155
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
306156
307157
<imports>
308-
<import resource="parameters.yml" />
309-
<import resource="/etc/sites/mysite.com/parameters.yml" />
158+
<import resource="/etc/sites/mysite.com/parameters.yaml" ignore-errors="true" />
310159
</imports>
311160
312161
<!-- ... -->
313162
</container>
314163
315164
.. code-block:: php
316165
317-
// app/config/config.php
318-
$loader->import('parameters.yml');
319-
$loader->import('/etc/sites/mysite.com/parameters.yml');
166+
// config/services.php
167+
$loader->import('/etc/sites/mysite.com/parameters.yaml', null, true);
320168
321169
// ...
322170
323-
Most of the time, local developers won't have the same files that exist on the
324-
production servers. For that reason, the Config component provides the
325-
``ignore_errors`` option to silently discard errors when the loaded file
326-
doesn't exist:
327-
328-
.. configuration-block::
329-
330-
.. code-block:: yaml
171+
.. tip::
331172

332-
# app/config/config.yml
333-
imports:
334-
- { resource: 'parameters.yml' }
335-
- { resource: '/etc/sites/mysite.com/parameters.yml', ignore_errors: true }
336-
337-
# ...
338-
339-
.. code-block:: xml
340-
341-
<!-- app/config/config.xml -->
342-
<?xml version="1.0" encoding="UTF-8" ?>
343-
<container xmlns="http://symfony.com/schema/dic/services"
344-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
345-
xsi:schemaLocation="http://symfony.com/schema/dic/services
346-
http://symfony.com/schema/dic/services/services-1.0.xsd
347-
http://symfony.com/schema/dic/symfony
348-
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
349-
350-
<imports>
351-
<import resource="parameters.yml" />
352-
<import resource="/etc/sites/mysite.com/parameters.yml" ignore-errors="true" />
353-
</imports>
354-
355-
<!-- ... -->
356-
</container>
357-
358-
.. code-block:: php
359-
360-
// app/config/config.php
361-
$loader->import('parameters.yml');
362-
$loader->import('/etc/sites/mysite.com/parameters.yml', null, true);
363-
364-
// ...
173+
The ``ignore_errors`` option (which is the third optional argument in the
174+
loader's ``import()`` method) silently discards errors when the loaded file
175+
doesn't exist. This is needed in this case because most of the time, local
176+
developers won't have the same files that exist on the production servers.
365177

366178
As you've seen, there are lots of ways to organize your configuration files. You
367179
can choose one of these or even create your own custom way of organizing the
368-
files. Don't feel limited by the Standard Edition that comes with Symfony. For even
369-
more customization, see ":doc:`/configuration/override_dir_structure`".
180+
files. For even more customization, see ":doc:`/configuration/override_dir_structure`".

0 commit comments

Comments
 (0)
0