Configuring Symfony (and Environments)

Version: 2.3
Edit this page

Warning: You are browsing the documentation for Symfony 2.3, which is no longer maintained.

Read the updated version of this page for Symfony 6.0 (the current stable version).

Configuring Symfony (and Environments)

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:

  • YAML
  • XML
  • PHP 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 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%'

# ...

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 "The YAML Format");
  • XML: More powerful than YAML at times and supports IDE autocompletion;
  • PHP: Very powerful but less readable than standard configuration formats.

Default Configuration Dump

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:

1
$ php app/console config:dump-reference FrameworkBundle

The extension alias (configuration key) can also be used:

1
$ php app/console config:dump-reference framework

Note

See the cookbook article: How to Load Service Configuration inside a Bundle for information on adding configuration for your own bundle.

Environments

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:

1
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:

1
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:

1
$ php app/console cache:clear --env=prod --no-debug

Note

If you open the web/app.php file, you'll find that it's configured explicitly to use the prod environment:

1
$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 testing chapter for more details.

Tip

When using the server:run command to start a server, http://localhost:8000/ will use the dev front controller of your application.

Environment Configuration

The AppKernel class is responsible for actually loading the configuration file of your choice:

1
2
3
4
5
6
7
// 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.

  • YAML
  • XML
  • PHP 
1
2
3
4
5
6
7
8
9
# app/config/config_dev.yml
imports:
    - { resource: config.yml }

framework:
    router:   { resource: '%kernel.root_dir%/config/routing_dev.yml' }
    profiler: { 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.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.