Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • SensioLabs Professional services to help you with Symfony
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by
  1. Home
  2. Documentation
  3. Configuration
  4. How to Organize Configuration Files
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Advanced Techniques
    • Mix and Match Configuration Formats
    • Global Configuration Files

How to Organize Configuration Files

Edit this page

Warning: You are browsing the documentation for Symfony 4.1, which is no longer maintained.

Read the updated version of this page for Symfony 6.3 (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:

  1. config/packages/*
  2. config/packages/dev/*
  3. config/services.yaml
  4. 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):

1
2
3
4
5
6
# config/services.yaml
imports:
    - { resource: 'my_config_file.xml' }
    - { resource: 'legacy.php' }

# ...
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>
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. You can load files from outside the project folder by indicating the full file path when importing it from any other configuration file:

1
2
3
4
5
# config/services.yaml
imports:
    - { resource: '/etc/sites/mysite.com/parameters.yaml', ignore_errors: true }

# ...
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>
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.
TOC
    Version
    We stand with Ukraine.
    Version:
    Make sure your project is risk free

    Make sure your project is risk free

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Cedric BERTOLINI, a Symfony contributor

    Thanks Cedric BERTOLINI (@alsciende) for being a Symfony contributor

    2 commits • 8 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Meilisearch