Skip to content

Commit a7901c1

Browse files
weaverryanweaverryan
committed
Moving configuration/configuration.rst -> configuration.rst
1 parent cd5fe07 commit a7901c1

File tree

4 files changed

+289
-291
lines changed

4 files changed

+289
-291
lines changed

‎configuration.rst

Lines changed: 287 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,290 @@
1-
Configuration
2-
=============
1+
.. index::
2+
single: Configuration
3+
4+
Configuring Symfony (and Environments)
5+
======================================
6+
7+
An application consists of a collection of bundles representing all the
8+
features and capabilities of your application. Each bundle can be customized
9+
via configuration files written in YAML, XML or PHP. By default, the main
10+
configuration file lives in the ``app/config/`` directory and is called
11+
either ``config.yml``, ``config.xml`` or ``config.php`` depending on which
12+
format you prefer:
13+
14+
.. configuration-block::
15+
16+
.. code-block:: yaml
17+
18+
# app/config/config.yml
19+
imports:
20+
- { resource: parameters.yml }
21+
- { resource: security.yml }
22+
23+
framework:
24+
secret: '%secret%'
25+
router: { resource: '%kernel.root_dir%/config/routing.yml' }
26+
# ...
27+
28+
# Twig Configuration
29+
twig:
30+
debug: '%kernel.debug%'
31+
strict_variables: '%kernel.debug%'
32+
33+
# ...
34+
35+
.. code-block:: xml
36+
37+
<!-- app/config/config.xml -->
38+
<?xml version="1.0" encoding="UTF-8" ?>
39+
<container xmlns="http://symfony.com/schema/dic/services"
40+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
41+
xmlns:framework="http://symfony.com/schema/dic/symfony"
42+
xmlns:twig="http://symfony.com/schema/dic/twig"
43+
xsi:schemaLocation="http://symfony.com/schema/dic/services
44+
http://symfony.com/schema/dic/services/services-1.0.xsd
45+
http://symfony.com/schema/dic/symfony
46+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd
47+
http://symfony.com/schema/dic/twig
48+
http://symfony.com/schema/dic/twig/twig-1.0.xsd">
49+
50+
<imports>
51+
<import resource="parameters.yml" />
52+
<import resource="security.yml" />
53+
</imports>
54+
55+
<framework:config secret="%secret%">
56+
<framework:router resource="%kernel.root_dir%/config/routing.xml" />
57+
<!-- ... -->
58+
</framework:config>
59+
60+
<!-- Twig Configuration -->
61+
<twig:config debug="%kernel.debug%" strict-variables="%kernel.debug%" />
62+
63+
<!-- ... -->
64+
</container>
65+
66+
.. code-block:: php
67+
68+
// app/config/config.php
69+
$this->import('parameters.yml');
70+
$this->import('security.yml');
71+
72+
$container->loadFromExtension('framework', array(
73+
'secret' => '%secret%',
74+
'router' => array(
75+
'resource' => '%kernel.root_dir%/config/routing.php',
76+
),
77+
// ...
78+
));
79+
80+
// Twig Configuration
81+
$container->loadFromExtension('twig', array(
82+
'debug' => '%kernel.debug%',
83+
'strict_variables' => '%kernel.debug%',
84+
));
85+
86+
// ...
87+
88+
.. note::
89+
90+
You'll learn exactly how to load each file/format in the next section
91+
`Environments`_.
92+
93+
Each top-level entry like ``framework`` or ``twig`` defines the configuration
94+
for a particular bundle. For example, the ``framework`` key defines the configuration
95+
for the core Symfony FrameworkBundle and includes configuration for the
96+
routing, templating, and other core systems.
97+
98+
For now, don't worry about the specific configuration options in each section.
99+
The configuration file ships with sensible defaults. As you read more and
100+
explore each part of Symfony, you'll learn about the specific configuration
101+
options of each feature.
102+
103+
.. sidebar:: Configuration Formats
104+
105+
Throughout the chapters, all configuration examples will be shown in all
106+
three formats (YAML, XML and PHP). Each has its own advantages and
107+
disadvantages. The choice of which to use is up to you:
108+
109+
* *YAML*: Simple, clean and readable (learn more about YAML in
110+
":doc:`/components/yaml/yaml_format`");
111+
112+
* *XML*: More powerful than YAML at times and supports IDE autocompletion;
113+
114+
* *PHP*: Very powerful but less readable than standard configuration formats.
115+
116+
Default Configuration Dump
117+
~~~~~~~~~~~~~~~~~~~~~~~~~~
118+
119+
You can dump the default configuration for a bundle in YAML to the console using
120+
the ``config:dump-reference`` command. Here is an example of dumping the default
121+
FrameworkBundle configuration:
122+
123+
.. code-block:: bash
124+
125+
$ php app/console config:dump-reference FrameworkBundle
126+
127+
The extension alias (configuration key) can also be used:
128+
129+
.. code-block:: bash
130+
131+
$ php app/console config:dump-reference framework
132+
133+
.. note::
134+
135+
See the cookbook article: :doc:`/bundles/extension` for
136+
information on adding configuration for your own bundle.
137+
138+
.. index::
139+
single: Environments; Introduction
140+
141+
.. _environments-summary:
142+
.. _page-creation-environments:
143+
.. _book-page-creation-prod-cache-clear:
144+
145+
Environments
146+
------------
147+
148+
An application can run in various environments. The different environments
149+
share the same PHP code (apart from the front controller), but use different
150+
configuration. For instance, a ``dev`` environment will log warnings and
151+
errors, while a ``prod`` environment will only log errors. Some files are
152+
rebuilt on each request in the ``dev`` environment (for the developer's convenience),
153+
but cached in the ``prod`` environment. All environments live together on
154+
the same machine and execute the same application.
155+
156+
A Symfony project generally begins with three environments (``dev``, ``test``
157+
and ``prod``), though creating new environments is easy. You can view your
158+
application in different environments simply by changing the front controller
159+
in your browser. To see the application in the ``dev`` environment, access
160+
the application via the development front controller:
161+
162+
.. code-block:: text
163+
164+
http://localhost/app_dev.php/random/10
165+
166+
If you'd like to see how your application will behave in the production environment,
167+
call the ``prod`` front controller instead:
168+
169+
.. code-block:: text
170+
171+
http://localhost/app.php/random/10
172+
173+
Since the ``prod`` environment is optimized for speed; the configuration,
174+
routing and Twig templates are compiled into flat PHP classes and cached.
175+
When viewing changes in the ``prod`` environment, you'll need to clear these
176+
cached files and allow them to rebuild:
177+
178+
.. code-block:: bash
179+
180+
$ php app/console cache:clear --env=prod --no-debug
181+
182+
.. note::
183+
184+
If you open the ``web/app.php`` file, you'll find that it's configured explicitly
185+
to use the ``prod`` environment::
186+
187+
$kernel = new AppKernel('prod', false);
188+
189+
You can create a new front controller for a new environment by copying
190+
this file and changing ``prod`` to some other value.
191+
192+
.. note::
193+
194+
The ``test`` environment is used when running automated tests and cannot
195+
be accessed directly through the browser. See the :doc:`testing chapter </testing>`
196+
for more details.
197+
198+
.. tip::
199+
200+
When using the ``server:run`` command to start a server,
201+
``http://localhost:8000/`` will use the dev front controller of your
202+
application.
203+
204+
.. index::
205+
single: Environments; Configuration
206+
207+
Environment Configuration
208+
~~~~~~~~~~~~~~~~~~~~~~~~~
209+
210+
The ``AppKernel`` class is responsible for actually loading the configuration
211+
file of your choice::
212+
213+
// app/AppKernel.php
214+
public function registerContainerConfiguration(LoaderInterface $loader)
215+
{
216+
$loader->load(
217+
__DIR__.'/config/config_'.$this->getEnvironment().'.yml'
218+
);
219+
}
220+
221+
You already know that the ``.yml`` extension can be changed to ``.xml`` or
222+
``.php`` if you prefer to use either XML or PHP to write your configuration.
223+
Notice also that each environment loads its own configuration file. Consider
224+
the configuration file for the ``dev`` environment.
225+
226+
.. configuration-block::
227+
228+
.. code-block:: yaml
229+
230+
# app/config/config_dev.yml
231+
imports:
232+
- { resource: config.yml }
233+
234+
framework:
235+
router: { resource: '%kernel.root_dir%/config/routing_dev.yml' }
236+
profiler: { only_exceptions: false }
237+
238+
# ...
239+
240+
.. code-block:: xml
241+
242+
<!-- app/config/config_dev.xml -->
243+
<?xml version="1.0" encoding="UTF-8" ?>
244+
<container xmlns="http://symfony.com/schema/dic/services"
245+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
246+
xmlns:framework="http://symfony.com/schema/dic/symfony"
247+
xsi:schemaLocation="http://symfony.com/schema/dic/services
248+
http://symfony.com/schema/dic/services/services-1.0.xsd
249+
http://symfony.com/schema/dic/symfony
250+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
251+
252+
<imports>
253+
<import resource="config.xml" />
254+
</imports>
255+
256+
<framework:config>
257+
<framework:router resource="%kernel.root_dir%/config/routing_dev.xml" />
258+
<framework:profiler only-exceptions="false" />
259+
</framework:config>
260+
261+
<!-- ... -->
262+
</container>
263+
264+
.. code-block:: php
265+
266+
// app/config/config_dev.php
267+
$loader->import('config.php');
268+
269+
$container->loadFromExtension('framework', array(
270+
'router' => array(
271+
'resource' => '%kernel.root_dir%/config/routing_dev.php',
272+
),
273+
'profiler' => array('only-exceptions' => false),
274+
));
275+
276+
// ...
277+
278+
The ``imports`` key is similar to a PHP ``include`` statement and guarantees
279+
that the main configuration file (``config.yml``) is loaded first. The rest
280+
of the file tweaks the default configuration for increased logging and other
281+
settings conducive to a development environment.
282+
283+
Both the ``prod`` and ``test`` environments follow the same model: each environment
284+
imports the base configuration file and then modifies its configuration values
285+
to fit the needs of the specific environment. This is just a convention,
286+
but one that allows you to reuse most of your configuration and customize
287+
just pieces of it between environments.
3288

4289
.. toctree::
5290
:maxdepth: 1

0 commit comments

Comments
 (0)