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.
By default, Symfony adds these types of options to the .env
file when
installing new dependencies in the app:
| # .env
###> doctrine/doctrine-bundle ###
DATABASE_URL=sqlite:///%kernel.project_dir%/var/data/blog.sqlite
###< doctrine/doctrine-bundle ###
###> symfony/swiftmailer-bundle ###
MAILER_URL=smtp://localhost?encryption=ssl&auth_mode=login&username=&password=
###< symfony/swiftmailer-bundle ###
# ...
|
These options aren't defined inside the config/services.yaml
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.
To override these variables with machine-specific or sensitive values, create a
.env.local
file. This file should not be added to version control.
Caution
Beware that dumping the contents of the $_SERVER
and $_ENV
variables
or outputting the phpinfo()
contents will display the values of the
environment variables, exposing sensitive information such as the database
credentials.
Canonical Parameters
Best Practice
Define all your application's env vars in the .env
file.
Symfony includes a configuration file called .env
at the project root, which
stores the canonical list of environment variables for the application. This
file should be stored in version control and so should only contain non-sensitive
default values.
The services.yaml
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 .env
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 services.yaml
may vary from one
environment to another. That's why Symfony
supports defining config/services_dev.yaml
and config/services_prod.yaml
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 applications to include an option like the following, which would be
used to control the number of posts to display on the blog homepage:
| # 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:
| // 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:
| <p>
Displaying the {{ constant('NUMBER_OF_ITEMS', post) }} most recent results.
</p>
|
And Doctrine entities and repositories can access these values too, 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 it's complicated to redefine their values in your tests.