Canonical Parameters¶

Symfony includes a configuration file called .env.dist at the project root, which stores the canonical list of environment variables for the application.

Whenever a new env var is defined for the application, you should also add it to this file and submit the changes to your version control system so your workmates can update their .env files.

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

# config/services.yaml
parameters:
    homepage.number_of_items: 10

If you've done something like this in the past, it's likely that you've in fact never actually needed to change that value. 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 NUMBER_OF_ITEMS constant in the Post entity:

1
2
3
4
5
6
7
8
9

// src/Entity/Post.php
namespace App\Entity;

class Post
{
    const NUMBER_OF_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('NUMBER_OF_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 App\Repository;

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

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

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