You are browsing the Symfony 4 documentation, which changes significantly from Symfony 3.x. If your app doesn't use Symfony 4 yet, browse the Symfony 3.4 documentation.
How to Organize Configuration Files
How to Organize Configuration Files¶
The Symfony skeleton defines three execution environments
called dev
, prod
and test
. An environment simply 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.yaml
config/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
1 2 3 4 5 6
# config/services.yaml imports: - { resource: 'my_config_file.xml' } - { resource: 'legacy.php' } # ...
- XML
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<!-- config/services.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <imports> <import resource="my_config_file.yaml" /> <import resource="legacy.php" /> </imports> <!-- ... --> </container>
- PHP
1 2 3 4 5
// config/services.php $loader->import('my_config_file.yaml'); $loader->import('legacy.xml'); // ...
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. Loading
this file is as simple as indicating the full file path when importing it from
any other configuration file:
- YAML
1 2 3 4 5
# config/services.yaml imports: - { resource: '/etc/sites/mysite.com/parameters.yaml', ignore_errors: true } # ...
- XML
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<!-- config/services.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <imports> <import resource="/etc/sites/mysite.com/parameters.yaml" ignore-errors="true" /> </imports> <!-- ... --> </container>
- PHP
1 2 3 4
// config/services.php $loader->import('/etc/sites/mysite.com/parameters.yaml', null, 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".
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.