Skip to content

Commit b4866bd

Browse files
weaverryanweaverryan
authored
Merge pull request #69 from sensiolabs/page_creation
Page creation shortening & Configuration topic entry
2 parents c76a32b + e71d368 commit b4866bd

10 files changed

+483
-729
lines changed

‎configuration.rst

Lines changed: 372 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,378 @@
1-
Configuration
2-
=============
1+
.. index::
2+
single: Configuration
3+
4+
Configuring Symfony (and Environments)
5+
======================================
6+
7+
Every Symfony application consists of a collection of bundles that add useful tools
8+
(:doc:`services </service_container>`) to your project. Each bundle can be customized
9+
via configuration files that live - by default - in the ``app/config`` directory.
10+
11+
Configuration: config.yml
12+
-------------------------
13+
14+
The main configuration file is called ``config.yml``:
15+
16+
.. configuration-block::
17+
18+
.. code-block:: yaml
19+
20+
# app/config/config.yml
21+
imports:
22+
- { resource: parameters.yml }
23+
- { resource: security.yml }
24+
- { resource: services.yml }
25+
26+
framework:
27+
secret: '%secret%'
28+
router: { resource: '%kernel.root_dir%/config/routing.yml' }
29+
# ...
30+
31+
# Twig Configuration
32+
twig:
33+
debug: '%kernel.debug%'
34+
strict_variables: '%kernel.debug%'
35+
36+
# ...
37+
38+
.. code-block:: xml
39+
40+
<!-- app/config/config.xml -->
41+
<?xml version="1.0" encoding="UTF-8" ?>
42+
<container xmlns="http://symfony.com/schema/dic/services"
43+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
44+
xmlns:framework="http://symfony.com/schema/dic/symfony"
45+
xmlns:twig="http://symfony.com/schema/dic/twig"
46+
xsi:schemaLocation="http://symfony.com/schema/dic/services
47+
http://symfony.com/schema/dic/services/services-1.0.xsd
48+
http://symfony.com/schema/dic/symfony
49+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd
50+
http://symfony.com/schema/dic/twig
51+
http://symfony.com/schema/dic/twig/twig-1.0.xsd">
52+
53+
<imports>
54+
<import resource="parameters.yml" />
55+
<import resource="security.yml" />
56+
<import resource="services.yml" />
57+
</imports>
58+
59+
<framework:config secret="%secret%">
60+
<framework:router resource="%kernel.root_dir%/config/routing.xml" />
61+
<!-- ... -->
62+
</framework:config>
63+
64+
<!-- Twig Configuration -->
65+
<twig:config debug="%kernel.debug%" strict-variables="%kernel.debug%" />
66+
67+
<!-- ... -->
68+
</container>
69+
70+
.. code-block:: php
71+
72+
// app/config/config.php
73+
$this->import('parameters.yml');
74+
$this->import('security.yml');
75+
$this->import('services.yml');
76+
77+
$container->loadFromExtension('framework', array(
78+
'secret' => '%secret%',
79+
'router' => array(
80+
'resource' => '%kernel.root_dir%/config/routing.php',
81+
),
82+
// ...
83+
));
84+
85+
// Twig Configuration
86+
$container->loadFromExtension('twig', array(
87+
'debug' => '%kernel.debug%',
88+
'strict_variables' => '%kernel.debug%',
89+
));
90+
91+
// ...
92+
93+
Most top-level keys - like ``framework`` and ``twig`` - are configuration for a
94+
specific bundle (i.e. ``FrameworkBundle`` and ``TwigBundle``).
95+
96+
.. sidebar:: Configuration Formats
97+
98+
Throughout the chapters, all configuration examples will be shown in
99+
three formats (YAML, XML and PHP). YAML is used by default, but you can
100+
choose whatever you like best. There is no performance difference:
101+
102+
* :doc:`/components/yaml/yaml_format`: Simple, clean and readable;
103+
104+
* *XML*: More powerful than YAML at times & supports IDE autocompletion;
105+
106+
* *PHP*: Very powerful but less readable than standard configuration formats.
107+
108+
Configuration Reference & Dumping
109+
---------------------------------
110+
111+
There are *two* ways to know *what* keys you can configure:
112+
113+
#. Use the :doc:`Reference Section </reference/index>`;
114+
115+
#. Use the ``config:dump`` command;
116+
117+
For example, if you want to configure something in Twig, you can see an example
118+
dump of all available configuration options by running:
119+
120+
.. code-block:: bash
121+
122+
$ php app/console config:dump-reference twig
123+
124+
.. index::
125+
single: Environments; Introduction
126+
127+
.. _environments-summary:
128+
.. _page-creation-environments:
129+
.. _book-page-creation-prod-cache-clear:
130+
131+
The imports Key: Loading other Configuration Files
132+
--------------------------------------------------
133+
134+
Symfony's main configuration file is ``app/config/config.yml``. But, for organization,
135+
it *also* loads other configuration files via its ``imports`` key:
136+
137+
.. configuration-block::
138+
139+
.. code-block:: yaml
140+
141+
# app/config/config.yml
142+
imports:
143+
- { resource: parameters.yml }
144+
- { resource: security.yml }
145+
- { resource: services.yml }
146+
# ...
147+
148+
.. code-block:: xml
149+
150+
<!-- app/config/config.xml -->
151+
<?xml version="1.0" encoding="UTF-8" ?>
152+
<container xmlns="http://symfony.com/schema/dic/services"
153+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
154+
xmlns:framework="http://symfony.com/schema/dic/symfony"
155+
xmlns:twig="http://symfony.com/schema/dic/twig"
156+
xsi:schemaLocation="http://symfony.com/schema/dic/services
157+
http://symfony.com/schema/dic/services/services-1.0.xsd
158+
http://symfony.com/schema/dic/symfony
159+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd
160+
http://symfony.com/schema/dic/twig
161+
http://symfony.com/schema/dic/twig/twig-1.0.xsd">
162+
163+
<imports>
164+
<import resource="parameters.yml" />
165+
<import resource="security.yml" />
166+
<import resource="services.yml" />
167+
</imports>
168+
169+
<!-- ... -->
170+
</container>
171+
172+
.. code-block:: php
173+
174+
// app/config/config.php
175+
$this->import('parameters.yml');
176+
$this->import('security.yml');
177+
$this->import('services.yml');
178+
179+
// ...
180+
181+
The ``imports`` key works a lot like the PHP ``include`` function: the contents of
182+
``parameters.yml``, ``security.yml`` and ``services.yml`` are read and loaded. You
183+
can also load XML files or PHP files.
184+
185+
The parameters key: Parameters (Variables)
186+
------------------------------------------
187+
188+
Another special key is called ``parameters``: it's used to define *variables* that
189+
can be referenced in *any* other configuration file. For example, in ``config.yml``,
190+
a ``locale`` parameter is defined and then referenced below under the ``framework``
191+
key:
192+
193+
.. configuration-block::
194+
195+
.. code-block:: yaml
196+
197+
# app/config/config.yml
198+
# ...
199+
200+
parameters:
201+
locale: en
202+
203+
framework:
204+
# ...
205+
206+
# any string surrounded by two % is replaced by that parameter value
207+
default_locale: "%locale%"
208+
209+
# ...
210+
211+
.. code-block:: xml
212+
213+
<!-- app/config/config.xml -->
214+
<?xml version="1.0" encoding="UTF-8" ?>
215+
<container xmlns="http://symfony.com/schema/dic/services"
216+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
217+
xmlns:framework="http://symfony.com/schema/dic/symfony"
218+
xmlns:twig="http://symfony.com/schema/dic/twig"
219+
xsi:schemaLocation="http://symfony.com/schema/dic/services
220+
http://symfony.com/schema/dic/services/services-1.0.xsd
221+
http://symfony.com/schema/dic/symfony
222+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd
223+
http://symfony.com/schema/dic/twig
224+
http://symfony.com/schema/dic/twig/twig-1.0.xsd">
225+
226+
<!-- ... -->
227+
<parameters>
228+
<parameter key="locale">en</parameter>
229+
</parameters>
230+
231+
<framework:config default-locale="%locale%">
232+
<!-- ... -->
233+
</framework:config>
234+
235+
<!-- ... -->
236+
</container>
237+
238+
.. code-block:: php
239+
240+
// app/config/config.php
241+
// ...
242+
243+
$container->setParameter('locale', 'en');
244+
245+
$container->loadFromExtension('framework', array(
246+
'default_locale' => '%en%',
247+
// ...
248+
));
249+
250+
// ...
251+
252+
You can define whatever parameter names you want under the ``parameters`` key of
253+
any configuration file. To reference a parameter, surround its name with two percent
254+
signs - e.g. ``%locale%``.
255+
256+
.. seealso::
257+
258+
You can also set parameters dynamically, like from environment variables.
259+
See :doc:`/configuration/external_parameters`.
260+
261+
For more information about parameters - including how to reference them from inside
262+
a controller - see :ref:`book-service-container-parameters`.
263+
264+
.. _config-parameters-yml:
265+
266+
The Special parameters.yml File
267+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
268+
269+
On the surface, ``parameters.yml`` is just like any other configuration file: it
270+
is imported by ``config.yml`` and defines several parameters:
271+
272+
.. code-block:: yaml
273+
274+
parameters:
275+
# ...
276+
database_user: root
277+
database_password: ~
278+
279+
Not surprisingly, these are referenced from inside of ``config.yml`` and help to
280+
configure DoctrineBundle and other parts of Symfony:
281+
282+
.. configuration-block::
283+
284+
.. code-block:: yaml
285+
286+
# app/config/config.yml
287+
doctrine:
288+
dbal:
289+
driver: pdo_mysql
290+
# ...
291+
user: '%database_user%'
292+
password: '%database_password%'
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+
xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
301+
xsi:schemaLocation="http://symfony.com/schema/dic/services
302+
http://symfony.com/schema/dic/services/services-1.0.xsd
303+
http://symfony.com/schema/dic/doctrine
304+
http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
305+
306+
<doctrine:config>
307+
<doctrine:dbal
308+
driver="pdo_mysql"
309+
310+
user="%database_user%"
311+
password="%database_password%" />
312+
</doctrine:config>
313+
</container>
314+
315+
.. code-block:: php
316+
317+
// app/config/config.php
318+
$configuration->loadFromExtension('doctrine', array(
319+
'dbal' => array(
320+
'driver' => 'pdo_mysql',
321+
// ...
322+
323+
'user' => '%database_user%',
324+
'password' => '%database_password%',
325+
),
326+
));
327+
328+
But the ``parameters.yml`` file *is* special: it defines the values that usually
329+
change on each server. For example, the database credentials on your local
330+
development machine might be different from your workmates. That's why this file
331+
is not committed to the shared repository and is only stored on your machine.
332+
333+
Because of that, **parameters.yml is not committed to your version control**. In fact,
334+
the ``.gitignore`` file that comes with Symfony prevents it from being committed.
335+
336+
However, a ``parameters.yml.dist`` file *is* committed (with dummy values). This file
337+
isn't read by Symfony: it's just a reference so that Symfony knows which parameters
338+
need to be defined in the ``parameters.yml`` file. If you add or remove keys to
339+
``parameters.yml``, add or remove them from ``parameters.yml.dist`` too so both
340+
files are always in sync.
341+
342+
.. sidebar:: The Interactive Parameter Handler
343+
344+
When you :ref:`install an existing Symfony project <install-existing-app>`, you
345+
will need to create the ``parameters.yml`` file using the committed ``parameters.yml.dist``
346+
file as a reference. To help with this, after you run ``composer install``, a
347+
Symfony script will automatically create this file by interactively asking you
348+
to supply the value for each parameter defined in ``parameters.yml.dist``. For
349+
more details - or to remove or control this behavior - see the
350+
`Incenteev Parameter Handler`_ documentation.
351+
352+
Environments & the Other Config Files
353+
-------------------------------------
354+
355+
You have just *one* app, but whether you realize it or not, you need it to behave
356+
*differently* at different times:
357+
358+
* While **developing**, you want your app to log everything and expose nice debugging
359+
tools;
360+
361+
* After deploying to **production**, you want that *same* app to be optimized for
362+
speed and only log errors.
363+
364+
How can you make *one* application behave in two different ways? With *environments*.
365+
366+
You've probably already been using the ``dev`` environment without even knowing it.
367+
After you deploy, you'll use the ``prod`` environment.
368+
369+
To learn more about *how* to execute and control each environment, see
370+
:doc:`/configuration/environments`.
3371

4372
.. toctree::
5373
:maxdepth: 1
6374
:glob:
7375

8376
configuration/*
377+
378+
.. _`Incenteev Parameter Handler`: https://github.com/Incenteev/ParameterHandler

0 commit comments

Comments
 (0)