Configuring Symfony (Symfony Docs)

Symfony applications are configured with the files stored in the config/ directory, which has this default structure:
Packages (also called "bundles" in Symfony and "plugins/modules" in other projects) add ready-to-use features to your projects.
When using Symfony Flex, which is enabled by default in Symfony applications, packages update the bundles.php file and create new files in config/packages/ automatically during their installation. For example, this is the default file created by the "API Platform" bundle:
Splitting the configuration into lots of small files might seem intimidating to some Symfony newcomers. However, you'll get used to them quickly and you rarely need to change these files after package installation.
To learn about all the available configuration options, check out the Symfony Configuration Reference or run the config:dump-reference command.
Unlike other frameworks, Symfony doesn't impose a specific format on you to configure your applications, but lets you choose between YAML and PHP. Throughout the Symfony documentation, all configuration examples will be shown in these two formats.
There isn't any practical difference between formats. In fact, Symfony transforms all of them into PHP and caches them before running the application, so there's not even any performance difference.
YAML is used by default when installing packages because it's concise and very readable. These are the main advantages and disadvantages of each format:
Symfony loads configuration files using the Config component, which provides advanced features such as importing other configuration files, even if they use a different format:
Parameters are key-value pairs stored in the service container. They let you centralize configuration values, reuse them across your application's configuration, and inject them into services.
When the same configuration value is used in several places, define it as a parameter to avoid repetition. Parameters can also be overridden per environment. By convention, parameters are defined under the parameters key in the config/services.yaml file:
Once defined, you can reference this parameter value from any other configuration file using a special syntax: wrap the parameter name in two % (e.g. %app.admin_email%):
If some parameter value includes the % character, you need to escape it by adding another %, so Symfony doesn't consider it a reference to a parameter name:
Due to the way in which parameters are resolved, you cannot use them to build paths in imports dynamically. This means that something like the following does not work:
Configuration parameters are very common in Symfony applications. Symfony itself defines several parameters, including those related to the kernel configuration (e.g. kernel.project_dir, kernel.debug), and some packages add their own parameters to your config/services.yaml when installed.
By convention, parameters whose names start with a dot . (for example, .mailer.transport) are available only during the container compilation. They are useful when working with Compiler Passes to declare some temporary parameters that won't be available later in the application.
Configuration parameters are usually validation-free, but you can ensure that essential parameters for your application's functionality are not empty:
If a non-empty parameter is null, an empty string '', or an empty array [], Symfony will throw an exception. This validation is not performed at compile time but when attempting to retrieve the value of the parameter.
Later in this article you can read how to get configuration parameters in controllers and services.
You have only one application, but whether you realize it or not, you need it to behave differently at different times:
The files stored in config/packages/ are used by Symfony to configure the application services. In other words, you can change the application behavior by changing which configuration files are loaded. That's the idea of Symfony's configuration environments.
A typical Symfony application begins with three environments:
When running the application, Symfony loads the configuration files in this order (the last files can override the values set in the previous ones):
Take the framework package, installed by default, as an example:
In reality, each environment differs only somewhat from the others. This means that all environments share a large base of common configuration, which is put in files directly in the config/packages/ directory.
You can also define options for different environments in a single configuration file using the special when keyword:
When using PHP closures to configure your services, besides calling the $container->env() method shown above, you can automatically inject the current environment value by adding a string argument named $env to the closure:
See the configureContainer() method of the Kernel class to learn everything about the loading order of configuration files.
Symfony applications come with a file called .env located at the project root directory. This file is used to define the value of environment variables and it's explained in detail later in this article.
Open the .env file (or better, the .env.local file if you created one) and edit the value of the APP_ENV variable to change the environment in which the application runs. For example, to run the application in production:
This value is used both for the web and for the console commands. However, you can override it for commands by setting the APP_ENV value before running them:
The default three environments provided by Symfony are enough for most projects, but you can define your own environments too. For example, this is how you can define a staging environment where the client can test the project before going to production:
It's common for environments to be similar to each other, so you can use symbolic links between config/packages/<environment-name>/ directories to reuse the same configuration.
Instead of crea