English spoken conference
Talks Workshops Register
Front cover of the Symfony 5: The Fast Track book

Symfony 5: The Fast Track

A new book to learn about developing modern Symfony 5 applications.

Support this project

  1. Home
  2. Documentation
  3. Service Container
  4. How to Import Configuration Files/Resources
WARNING: You are browsing the documentation for Symfony 2.8 which is not maintained anymore. Consider upgrading your projects to Symfony 4.3.

How to Import Configuration Files/Resources

2.8 version
Maintained
3.4 4.3 current 4.4 5.0 master
Unmaintained
2.7 3.0 3.1 3.2 3.3 4.0 4.1 4.2

How to Import Configuration Files/Resources

Tip

In this section, service configuration files are referred to as resources. This is to highlight the fact that, while most configuration resources will be files (e.g. YAML, XML, PHP), Symfony is so flexible that configuration could be loaded from anywhere (e.g. a database or even via an external web service).

The service container is built using a single configuration resource (app/config/config.yml by default). All other service configuration (including the core Symfony and third-party bundle configuration) must be imported from inside this file in one way or another. This gives you absolute flexibility over the services in your application.

External service configuration can be imported in two different ways. The first method, commonly used to import other resources, is via the imports directive. The second method, using dependency injection extensions, is used by third-party bundles to load the configuration. Read on to learn more about both methods.

Importing Configuration with imports

So far, you've placed your app.mailer service container definition directly in the services configuration file (e.g. app/config/services.yml). If your application ends up having many services, this file becomes huge and hard to maintain. To avoid this, you can split your service configuration into multiple service files:

  • YAML
    1
2
3
4
5
6
7
8
    # app/config/services/mailer.yml
parameters:
    app.mailer.transport: sendmail

services:
    app.mailer:
        class:     AppBundle\Mailer
        arguments: ['%app.mailer.transport%']
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    <!-- app/config/services/mailer.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">

    <parameters>
        <parameter key="app.mailer.transport">sendmail</parameter>
    </parameters>

    <services>
        <service id="app.mailer" class="AppBundle\Mailer">
            <argument>%app.mailer.transport%</argument>
        </service>
    </services>
</container>
  • PHP
    1
2
3
4
5
6
7
    // app/config/services/mailer.php
use AppBundle\Mailer;

$container->setParameter('app.mailer.transport', 'sendmail');

$container->register('app.mailer', Mailer::class)
    ->addArgument('%app.mailer.transport%');

The definition itself hasn't changed, only its location. To make the service container load the definitions in this resource file, use the imports key in any already loaded resource (e.g. app/config/services.yml or app/config/config.yml):

  • YAML
    1
2
3
    # app/config/services.yml
imports:
    - { resource: services/mailer.yml }
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    <!-- app/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">

    <imports>
        <import resource="services/mailer.xml"/>
    </imports>
</container>
  • PHP
    1
2
    // app/config/services.php
$loader->import('services/mailer.php');

The resource location, for files, is either a relative path from the current file or an absolute path.

Note

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 doesn't work:

  • YAML
    1
2
3
    # app/config/config.yml
imports:
    - { resource: '%kernel.root_dir%/parameters.yml' }
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    <!-- app/config/config.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">

    <imports>
        <import resource="%kernel.root_dir%/parameters.yml" />
    </imports>
</container>
  • PHP
    1
2
    // app/config/config.php
$loader->import('%kernel.root_dir%/parameters.yml');

Importing Configuration via Container Extensions

Third-party bundle container configuration, including Symfony core services, are usually loaded using another method that's more flexible and easy to configure in your application.

Internally, each bundle defines its services like you've seen so far. However, these files aren't imported using the import directive. These bundles use a dependency injection extension to load the files. The extension also allows bundles to provide configuration to dynamically load some services.

Take the FrameworkBundle - the core Symfony Framework bundle - as an example. The presence of the following code in your application configuration invokes the service container extension inside the FrameworkBundle:

  • YAML
    1
2
3
4
5
    # app/config/config.yml
framework:
    secret: xxxxxxxxxx
    form:   true
    # ...
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
    <!-- app/config/config.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"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    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">

    <framework:config secret="xxxxxxxxxx">
        <framework:form />

        <!-- ... -->
    </framework:config>
</container>
  • PHP
    1
2
3
4
5
6
    // app/config/config.php
$container->loadFromExtension('framework', array(
    'secret' => 'xxxxxxxxxx',
    'form'   => array(),
    // ...
));

When the resources are parsed, the container looks for an extension that can handle the framework directive. The extension in question, which lives in the FrameworkBundle, is invoked and the service configuration for the FrameworkBundle is loaded.

The settings under the framework directive (e.g. form: true) indicate that the extension should load all services related to the Form component. If form was disabled, these services wouldn't be loaded and Form integration would not be available.

When installing or configuring a bundle, see the bundle's documentation for how the services for the bundle should be installed and configured. The options available for the core bundles can be found inside the Reference Guide.

If you want to use dependency injection extensions in your own shared bundles and provide user friendly configuration, take a look at the How to Load Service Configuration inside a Bundle article.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.