Configuring Symfony (and Environments)

Version: 3.1
Edit this page

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

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

Configuring Symfony (and Environments)

Every Symfony application consists of a collection of bundles that add useful tools (services) to your project. Each bundle can be customized via configuration files that live - by default - in the app/config directory.

Configuration: config.yml

The main configuration file is called config.yml:

  • YAML
  • XML
  • PHP 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# app/config/config.yml
imports:
    - { resource: parameters.yml }
    - { resource: security.yml }
    - { resource: services.yml }

framework:
    secret:          '%secret%'
    router:          { resource: '%kernel.root_dir%/config/routing.yml' }
    # ...

# Twig Configuration
twig:
    debug:            '%kernel.debug%'
    strict_variables: '%kernel.debug%'

# ...

Most top-level keys - like framework and twig - are configuration for a specific bundle (i.e. FrameworkBundle and TwigBundle).

Configuration Formats

Throughout the chapters, all configuration examples will be shown in three formats (YAML, XML and PHP). YAML is used by default, but you can choose whatever you like best. There is no performance difference:

  • The YAML Format: Simple, clean and readable;
  • XML: More powerful than YAML at times & supports IDE autocompletion;
  • PHP: Very powerful but less readable than standard configuration formats.

Configuration Reference & Dumping

There are two ways to know what keys you can configure:

  1. Use the Reference Section;
  2. Use the config:dump-reference command.

For example, if you want to configure something in Twig, you can see an example dump of all available configuration options by running:

1
$ php bin/console config:dump-reference twig

The imports Key: Loading other Configuration Files

Symfony's main configuration file is app/config/config.yml. But, for organization, it also loads other configuration files via its imports key:

  • YAML
  • XML
  • PHP 
1
2
3
4
5
6
# app/config/config.yml
imports:
    - { resource: parameters.yml }
    - { resource: security.yml }
    - { resource: services.yml }
# ...

The imports key works a lot like the PHP include() function: the contents of parameters.yml, security.yml and services.yml are read and loaded. You can also load XML files or PHP files.

The parameters Key: Parameters (Variables)

Another special key is called parameters: it's used to define variables that can be referenced in any other configuration file. For example, in config.yml, a locale parameter is defined and then referenced below under the framework key:

  • YAML
  • XML
  • PHP 
1
2
3
4
5
6
7
8
9
10
11
12
13
# app/config/config.yml
# ...

parameters:
    locale: en

framework:
    # ...

    # any string surrounded by two % is replaced by that parameter value
    default_locale:  "%locale%"

# ...

You can define whatever parameter names you want under the parameters key of any configuration file. To reference a parameter, surround its name with two percent signs - e.g. %locale%.

See also

You can also set parameters dynamically, like from environment variables. See How to Set external Parameters in the Service Container.

For more information about parameters - including how to reference them from inside a controller - see Service Container.

The Special parameters.yml File

On the surface, parameters.yml is just like any other configuration file: it is imported by config.yml and defines several parameters:

1
2
3
4
parameters:
    # ...
    database_user:      root
    database_password:  ~

Not surprisingly, these are referenced from inside of config.yml and help to configure DoctrineBundle and other parts of Symfony:

  • YAML
  • XML
  • PHP 
1
2
3
4
5
6
7
# app/config/config.yml
doctrine:
    dbal:
        driver:   pdo_mysql
        # ...
        user:     '%database_user%'
        password: '%database_password%'

But the parameters.yml file is special: it defines the values that usually change on each server. For example, the database credentials on your local development machine might be different from your workmates. That's why this file is not committed to the shared repository and is only stored on your machine.

Because of that, parameters.yml is not committed to your version control. In fact, the .gitignore file that comes with Symfony prevents it from being committed.

However, a parameters.yml.dist file is committed (with dummy values). This file isn't read by Symfony: it's just a reference so that Symfony knows which parameters need to be defined in the parameters.yml file. If you add or remove keys to parameters.yml, add or remove them from parameters.yml.dist too so both files are always in sync.

The Interactive Parameter Handler

When you install an existing Symfony project, you will need to create the parameters.yml file using the committed parameters.yml.dist file as a reference. To help with this, after you run composer install, a Symfony script will automatically create this file by interactively asking you to supply the value for each parameter defined in parameters.yml.dist. For more details - or to remove or control this behavior - see the Incenteev Parameter Handler documentation.

Environments & the Other Config Files

You have just one app, but whether you realize it or not, you need it to behave differently at different times:

  • While developing, you want your app to log everything and expose nice debugging tools;
  • After deploying to production, you want that same app to be optimized for speed and only log errors.

How can you make one application behave in two different ways? With environments.

You've probably already been using the dev environment without even knowing it. After you deploy, you'll use the prod environment.

To learn more about how to execute and control each environment, see How to Master and Create new Environments.

Keep Going!

Congratulations! You've tackled the basics in Symfony. Next, learn about each part of Symfony individually by following the guides. Check out:

And the many other topics.

Learn more

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