How to Organize Configuration Files
Edit this pageWarning: You are browsing the documentation for Symfony 4.1, which is no longer maintained.
Read the updated version of this page for Symfony 6.1 (the current stable version).
How to Organize Configuration Files
The Symfony skeleton defines three execution environments
called dev, prod and test. An environment represents a way
to execute the same codebase with different configurations.
In order to select the configuration file to load for each environment, Symfony
executes the configureContainer() method of the Kernel class:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
// src/Kernel.php
use Symfony\Component\Config\Loader\LoaderInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;
class Kernel extends BaseKernel
{
const CONFIG_EXTS = '.{php,xml,yaml,yml}';
// ...
public function configureContainer(ContainerBuilder $container, LoaderInterface $loader)
{
$confDir = $this->getProjectDir().'/config';
$loader->load($confDir.'/packages/*'.self::CONFIG_EXTS, 'glob');
if (is_dir($confDir.'/packages/'.$this->environment)) {
$loader->load($confDir.'/packages/'.$this->environment.'/**/*'.self::CONFIG_EXTS, 'glob');
}
$loader->load($confDir.'/services'.self::CONFIG_EXTS, 'glob');
$loader->load($confDir.'/services_'.$this->environment.self::CONFIG_EXTS, 'glob');
}
}For the dev environment, Symfony loads the following config files and
directories and in this order:
config/packages/*config/packages/dev/*config/services.yamlconfig/services_dev.yaml
Therefore, the configuration files of the default Symfony applications follow this structure:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
your-project/
├─ config/
│ ├─ packages/
│ │ ├─ dev/
│ │ │ ├─ framework.yaml
│ │ │ └─ ...
│ │ ├─ prod/
│ │ │ └─ ...
│ │ ├─ test/
│ │ │ └─ ...
│ │ ├─ framework.yaml
│ │ └─ ...
│ ├─ services.yaml
│ └─ services_dev.yaml
├─ ...This default structure was chosen for its simplicity — one file per package and environment. But as any other Symfony feature, you can customize it to better suit your needs.
Advanced Techniques
Symfony loads configuration files using the Config component, which provides some advanced features.
Mix and Match Configuration Formats
Configuration files can import files defined with any other built-in configuration
format (.yaml or .yml, .xml, .php, .ini):
- YAML
- XML
- PHP
1 2 3 4 5 6
# config/services.yaml
imports:
- { resource: 'my_config_file.xml' }
- { resource: 'legacy.php' }
# ...If you use any other configuration format, you have to define your own loader class extending it from FileLoader. When the configuration values are dynamic, you can use the PHP configuration file to execute your own logic. In addition, you can define your own services to load configurations from databases or web services.
Global Configuration Files
Some system administrators may prefer to store sensitive parameters in files
outside the project directory. Imagine that the database credentials for your
website are stored in the /etc/sites/mysite.com/parameters.yaml file. You
can load files from outside the project folder by indicating the full file path
when importing it from any other configuration file:
- YAML
- XML
- PHP
1 2 3 4 5
# config/services.yaml
imports:
- { resource: '/etc/sites/mysite.com/parameters.yaml', ignore_errors: true }
# ...Tip
The ignore_errors option (which is the third optional argument in the
loader's import() method) silently discards errors when the loaded file
doesn't exist. This is needed in this case because most of the time, local
developers won't have the same files that exist on the production servers.
As you've seen, there are lots of ways to organize your configuration files. You can choose one of these or even create your own custom way of organizing the files. For even more customization, see "How to Override Symfony's default Directory Structure".
