Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Configuring Symfony (and Environments)
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Configuration: config.yml
  • Configuration Reference & Dumping
  • The imports Key: Loading other Configuration Files
  • The parameters Key: Parameters (Variables)
    • The Special parameters.yml File
  • Environments & the Other Config Files
  • Keep Going!
  • Learn more

Configuring Symfony (and Environments)

Edit this page

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

Read the updated version of this page for Symfony 6.2 (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%'

# ...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<!-- 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" />
        <import resource="services.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>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// app/config/config.php
$this->import('parameters.yml');
$this->import('security.yml');
$this->import('services.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%',
));

// ...

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

Configuration Formats

Throughout the documentation, 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 app/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 }
# ...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!-- 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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd">

    <imports>
        <import resource="parameters.yml" />
        <import resource="security.yml" />
        <import resource="services.yml" />
    </imports>

    <!-- ... -->
</container>
1
2
3
4
5
6
// app/config/config.php
$this->import('parameters.yml');
$this->import('security.yml');
$this->import('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%"

# ...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!-- 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"
    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">

    <!-- ... -->
    <parameters>
        <parameter key="locale">en</parameter>
    </parameters>

    <framework:config default-locale="%locale%">
        <!-- ... -->
    </framework:config>

    <!-- ... -->
</container>
1
2
3
4
5
6
7
8
9
10
11
// app/config/config.php
// ...

$container->setParameter('locale', 'en');

$container->loadFromExtension('framework', array(
    '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%'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!-- 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:doctrine="http://symfony.com/schema/dic/doctrine"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/doctrine
        http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">

    <doctrine:config>
        <doctrine:dbal
            driver="pdo_mysql"

            user="%database_user%"
            password="%database_password%" />
    </doctrine:config>
</container>
1
2
3
4
5
6
7
8
9
10
// app/config/config.php
$container->loadFromExtension('doctrine', array(
    'dbal' => array(
        '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:

  • Forms
  • Databases and the Doctrine ORM
  • Service Container
  • Security
  • How to Send an Email
  • Logging with Monolog

And the many other topics.

Learn more

  • How to Use the Apache Router
  • How to Organize Configuration Files
  • How to Master and Create new Environments
  • How to Set external Parameters in the Service Container
  • Understanding how the Front Controller, Kernel and Environments Work together
  • Building your own Framework with the MicroKernelTrait
  • How To Create Symfony Applications with Multiple Kernels
  • How to Override Symfony's default Directory Structure
  • Using Parameters within a Dependency Injection Class
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Make sure your project is risk free

    Make sure your project is risk free

    Measure & Improve Symfony Code Performance

    Measure & Improve Symfony Code Performance

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Klaas Naaijkens, a Symfony contributor

    Thanks Klaas Naaijkens for being a Symfony contributor

    1 commit • 4 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia