.. index:: single: Configuration
An application consists of a collection of bundles representing all the
features and capabilities of your application. Each bundle can be customized
via configuration files written in YAML, XML or PHP. By default, the main
configuration file lives in the app/config/ directory and is called
either config.yml, config.xml or config.php depending on which
format you prefer:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: parameters.yml }
- { resource: security.yml }
framework:
secret: "%secret%"
router: { resource: "%kernel.root_dir%/config/routing.yml" }
# ...
# Twig Configuration
twig:
debug: "%kernel.debug%"
strict_variables: "%kernel.debug%"
# ...
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xmlns:twig="http://symfony.com/schema/dic/twig"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd
http://symfony.com/schema/dic/twig
http://symfony.com/schema/dic/twig/twig-1.0.xsd">
<imports>
<import resource="parameters.yml" />
<import resource="security.yml" />
</imports>
<framework:config secret="%secret%">
<framework:router resource="%kernel.root_dir%/config/routing.xml" />
<!-- ... -->
</framework:config>
<!-- Twig Configuration -->
<twig:config debug="%kernel.debug%" strict-variables="%kernel.debug%" />
<!-- ... -->
</container>
.. code-block:: php
// app/config/config.php
$this->import('parameters.yml');
$this->import('security.yml');
$container->loadFromExtension('framework', array(
'secret' => '%secret%',
'router' => array(
'resource' => '%kernel.root_dir%/config/routing.php',
),
// ...
));
// Twig Configuration
$container->loadFromExtension('twig', array(
'debug' => '%kernel.debug%',
'strict_variables' => '%kernel.debug%',
));
// ...
Note
You'll learn exactly how to load each file/format in the next section Environments.
Each top-level entry like framework or twig defines the configuration
for a particular bundle. For example, the framework key defines the configuration
for the core Symfony FrameworkBundle and includes configuration for the
routing, templating, and other core systems.
For now, don't worry about the specific configuration options in each section. The configuration file ships with sensible defaults. As you read more and explore each part of Symfony, you'll learn about the specific configuration options of each feature.
Configuration Formats
Throughout the chapters, all configuration examples will be shown in all three formats (YAML, XML and PHP). Each has its own advantages and disadvantages. The choice of which to use is up to you:
- YAML: Simple, clean and readable (learn more about YAML in ":doc:`/components/yaml/yaml_format`");
- XML: More powerful than YAML at times and supports IDE autocompletion;
- PHP: Very powerful but less readable than standard configuration formats.
You can dump the default configuration for a bundle in YAML to the console using
the config:dump-reference command. Here is an example of dumping the default
FrameworkBundle configuration:
$ app/console config:dump-reference FrameworkBundleThe extension alias (configuration key) can also be used:
$ app/console config:dump-reference frameworkNote
See the cookbook article: :doc:`/cookbook/bundles/extension` for information on adding configuration for your own bundle.
.. index:: single: Environments; Introduction
An application can run in various environments. The different environments
share the same PHP code (apart from the front controller), but use different
configuration. For instance, a dev environment will log warnings and
errors, while a prod environment will only log errors. Some files are
rebuilt on each request in the dev environment (for the developer's convenience),
but cached in the prod environment. All environments live together on
the same machine and execute the same application.
A Symfony project generally begins with three environments (dev, test
and prod), though creating new environments is easy. You can view your
application in different environments simply by changing the front controller
in your browser. To see the application in the dev environment, access
the application via the development front controller:
http://localhost/app_dev.php/random/10
If you'd like to see how your application will behave in the production environment,
call the prod front controller instead:
http://localhost/app.php/random/10
Since the prod environment is optimized for speed; the configuration,
routing and Twig templates are compiled into flat PHP classes and cached.
When viewing changes in the prod environment, you'll need to clear these
cached files and allow them to rebuild:
$ php app/console cache:clear --env=prod --no-debugNote
If you open the web/app.php file, you'll find that it's configured explicitly
to use the prod environment:
$kernel = new AppKernel('prod', false);
You can create a new front controller for a new environment by copying
this file and changing prod to some other value.
Note
The test environment is used when running automated tests and cannot
be accessed directly through the browser. See the :doc:`testing chapter </book/testing>`
for more details.
.. index:: single: Environments; Configuration
The AppKernel class is responsible for actually loading the configuration
file of your choice:
// app/AppKernel.php
public function registerContainerConfiguration(LoaderInterface $loader)
{
$loader->load(
__DIR__.'/config/config_'.$this->getEnvironment().'.yml'
);
}
You already know that the .yml extension can be changed to .xml or
.php if you prefer to use either XML or PHP to write your configuration.
Notice also that each environment loads its own configuration file. Consider
the configuration file for the dev environment.
.. configuration-block::
.. code-block:: yaml
# app/config/config_dev.yml
imports:
- { resource: config.yml }
framework:
router: { resource: "%kernel.root_dir%/config/routing_dev.yml" }
profiler: { only_exceptions: false }
# ...
.. code-block:: xml
<!-- app/config/config_dev.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<imports>
<import resource="config.xml" />
</imports>
<framework:config>
<framework:router resource="%kernel.root_dir%/config/routing_dev.xml" />
<framework:profiler only-exceptions="false" />
</framework:config>
<!-- ... -->
</container>
.. code-block:: php
// app/config/config_dev.php
$loader->import('config.php');
$container->loadFromExtension('framework', array(
'router' => array(
'resource' => '%kernel.root_dir%/config/routing_dev.php',
),
'profiler' => array('only-exceptions' => false),
));
// ...
The imports key is similar to a PHP include statement and guarantees
that the main configuration file (config.yml) is loaded first. The rest
of the file tweaks the default configuration for increased logging and other
settings conducive to a development environment.
Both the prod and test environments follow the same model: each environment
imports the base configuration file and then modifies its configuration values
to fit the needs of the specific environment. This is just a convention,
but one that allows you to reuse most of your configuration and customize
just pieces of it between environments.