Configuration Files

Symfony compiles config/packages into the container; debug:config and config:dump-reference show what an option is really called.

Syntaxphp bin/console debug:config <alias> [<path>]

Configuration is how you set options on code you did not write. Symfony reads the files under config/ before it handles a request and compiles them into the container: the generated PHP class that holds every service and every setting. Editing a configuration file changes that generated class, not the framework.

One file per package

config/packages/ holds one file per installed package: framework.yaml, twig.yaml, mailer.yaml. The top-level key in each file is the package's alias, the short name a bundle registers for its own options, such as framework. Everything nested under that key is defined by that package. Your own classes are configured in config/services.yaml.

Files load in a fixed order, and a later value overwrites an earlier one: config/packages/*, then config/packages/<environment>/*, then config/services.yaml, then config/services_<environment>.yaml. YAML and PHP are interchangeable. The file extension chooses the syntax; the resulting container is the same.

Finding the real option name

Do not guess names. php bin/console config:dump-reference framework prints every option that package accepts, with its default. php bin/console debug:config framework prints the values your application actually ended up with once all files were merged. Both take a path to narrow the output, as in debug:config framework serializer.

What trips people up

An unrecognised key is not ignored. A misspelling fails the container build with Unrecognized option "..." under "framework" and a list of the valid ones, which means the mistake surfaces on the next request in dev and at cache-warmup time in prod.

Example

Example · php
// config/packages/framework.php
declare(strict_types=1);

// The Configurator namespace is what makes env() and App available in this file.
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

// This file is the PHP form of config/packages/framework.yaml.
// Either extension may be used; both compile to the same container.
return App::config([
    'framework' => [
        // read from the APP_SECRET environment variable, not hard-coded here
        'secret' => env('APP_SECRET'),
        'http_method_override' => false,
        'session' => [
            'handler_id' => null,
            'cookie_secure' => 'auto',
            'cookie_samesite' => 'lax',
        ],
    ],
]);

When to use it

  • Find the option that controls session cookie lifetime without guessing its name.
  • Check whether a package's default changed after a dependency upgrade.
  • Convert a project's configuration to PHP files so the editor autocompletes option names.

More examples

The same options in YAML

The YAML form of the primary example. Packages install their defaults as YAML, so this is the shape you will meet in an existing project. Reach for the PHP form when you want your editor to autocomplete and type-check option names; keep YAML when you want the shortest file.

Example · yaml
# config/packages/framework.yaml
framework:
    secret: '%env(APP_SECRET)%'
    http_method_override: false
    session:
        handler_id: null
        cookie_secure: auto
        cookie_samesite: lax

Asking the console what an option is called

Use config:dump-reference when you are looking for an option you have not used before, and debug:config when an option is set but not behaving. The second answers a different question: not what is possible, but what is in force right now.

Example · bash
# every option the framework package accepts, with defaults
$ php bin/console config:dump-reference framework

# what this application actually ended up with, after merging every file
$ php bin/console debug:config framework

# narrow it with a path when the output is long
$ php bin/console debug:config framework serializer

framework:
    serializer:
        enabled: true
        ...

What a misspelled key does

Worth seeing once so the message is recognisable. Configuration is validated against each package's definition, so a typo is a hard failure rather than a silently ignored line. In prod the failure happens when the cache is warmed, which is why a deploy should warm the cache before taking traffic.

Example · yaml
# config/packages/framework.yaml
framework:
    secret: '%env(APP_SECRET)%'
    # "sessions" is not an option; the real key is "session"
    sessions:
        cookie_samesite: lax

# Building the container now fails with:
#   Unrecognized option "sessions" under "framework".
#   Did you mean "session"?

Related

symfony parameterssymfony env varssymfony environmentssymfony bundlessymfony service config

Discussion

  • Be the first to comment on this lesson.