Canonical Parameters¶

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.

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.

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.