Symfony
sponsored by SensioLabs
Menu
  • About
  • Documentation
  • Screencasts
  • Cloud
  • Certification
  • Community
  • Businesses
  • News
  • Download
  1. Home
  2. Documentation
  3. Best Practices
  4. Configuration
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud
Search by Algolia

Table of Contents

  • Infrastructure-Related Configuration
    • Canonical Parameters
  • Application-Related Configuration
    • Constants vs Configuration Options
  • Semantic Configuration: Don't Do It
  • Moving Sensitive Options Outside of Symfony Entirely

Configuration

Edit this page

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

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

Configuration

Configuration usually involves different application parts (such as infrastructure and security credentials) and different environments (development, production). That's why Symfony recommends that you split the application configuration into three parts.

Infrastructure-Related Configuration

Best Practice

Define the infrastructure-related configuration options in the app/config/parameters.yml file.

The default parameters.yml file follows this recommendation and defines the options related to the database and mail server infrastructure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# app/config/parameters.yml
parameters:
    database_driver:   pdo_mysql
    database_host:     127.0.0.1
    database_port:     ~
    database_name:     symfony
    database_user:     root
    database_password: ~

    mailer_transport:  smtp
    mailer_host:       127.0.0.1
    mailer_user:       ~
    mailer_password:   ~

    # ...

These options aren't defined inside the app/config/config.yml file because they have nothing to do with the application's behavior. In other words, your application doesn't care about the location of your database or the credentials to access to it, as long as the database is correctly configured.

Canonical Parameters

Best Practice

Define all your application's parameters in the app/config/parameters.yml.dist file.

Since version 2.3, Symfony includes a configuration file called parameters.yml.dist, which stores the canonical list of configuration parameters for the application.

Whenever a new configuration parameter is defined for the application, you should also add it to this file and submit the changes to your version control system. Then, whenever a developer updates the project or deploys it to a server, Symfony will check if there is any difference between the canonical parameters.yml.dist file and your local parameters.yml file. If there is a difference, Symfony will ask you to provide a value for the new parameter and it will add it to your local parameters.yml file.

Application-Related Configuration

Best Practice

Define the application behavior related configuration options in the app/config/config.yml file.

The config.yml file contains the options used by the application to modify its behavior, such as the sender of email notifications, or the enabled feature toggles. Defining these values in parameters.yml file would add an extra layer of configuration that's not needed because you don't need or want these configuration values to change on each server.

The configuration options defined in the config.yml file usually vary from one environment to another. That's why Symfony already includes app/config/config_dev.yml and app/config/config_prod.yml files so that you can override specific values for each environment.

Constants vs Configuration Options

One of the most common errors when defining application configuration is to create new options for values that never change, such as the number of items for paginated results.

Best Practice

Use constants to define configuration options that rarely change.

The traditional approach for defining configuration options has caused many Symfony apps to include an option like the following, which would be used to control the number of posts to display on the blog homepage:

1
2
3
# app/config/config.yml
parameters:
    homepage.num_items: 10

If you ask yourself when the last time was that you changed the value of any option like this, odds are that you never have. Creating a configuration option for a value that you are never going to configure just isn't necessary. Our recommendation is to define these values as constants in your application. You could, for example, define a NUM_ITEMS constant in the Post entity:

1
2
3
4
5
6
7
8
9
// src/AppBundle/Entity/Post.php
namespace AppBundle\Entity;

class Post
{
    const NUM_ITEMS = 10;

    // ...
}

The main advantage of defining constants is that you can use their values everywhere in your application. When using parameters, they are only available from places with access to the Symfony container.

Constants can be used for example in your Twig templates thanks to the constant() function:

1
2
3
<p>
    Displaying the {{ constant('NUM_ITEMS', post) }} most recent results.
</p>

And Doctrine entities and repositories can now easily access these values, whereas they cannot access the container parameters:

1
2
3
4
5
6
7
8
9
10
11
12
namespace AppBundle\Repository;

use Doctrine\ORM\EntityRepository;
use AppBundle\Entity\Post;

class PostRepository extends EntityRepository
{
    public function findLatest($limit = Post::NUM_ITEMS)
    {
        // ...
    }
}

The only notable disadvantage of using constants for this kind of configuration values is that you cannot redefine them easily in your tests.

Semantic Configuration: Don't Do It

Best Practice

Don't define a semantic dependency injection configuration for your bundles.

As explained in How to Load Service Configuration inside a Bundle article, Symfony bundles have two choices on how to handle configuration: normal service configuration through the services.yml file and semantic configuration through a special *Extension class.

Although semantic configuration is much more powerful and provides nice features such as configuration validation, the amount of work needed to define that configuration isn't worth it for bundles that aren't meant to be shared as third-party bundles.

Moving Sensitive Options Outside of Symfony Entirely

When dealing with sensitive options, like database credentials, we also recommend that you store them outside the Symfony project and make them available through environment variables. Learn how to do it in the following article: How to Set external Parameters in the Service Container

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
We stand with Ukraine.
Version:
Online Sylius certification, take it now!

Online Sylius certification, take it now!

Measure & Improve Symfony Code Performance

Measure & Improve Symfony Code Performance

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

Avatar of Damien Tournoud, a Symfony contributor

Thanks Damien Tournoud for being a Symfony contributor

1 commit • 23 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