Configuration File Principles

Symfony configuration files are based on a common set of principles and share some common properties. This section describes them in detail, and acts as a reference for other sections describing YAML configuration files.

Cache

All configuration files in symfony are cached to PHP files by configuration handler classes. When the is_debug setting is set to false (for instance for the prod environment), the YAML file is only accessed for the very first request; the PHP cache is used for subsequent requests. This means that the "heavy" work is done only once, when the YAML file is parsed and interpreted the first time.

The parsing and caching of each configuration file is done by specialized configuration handler classes, configured in config_handler.yml.

In the following sections, when we talk about the "compilation", it means the first time when the YAML file is converted to a PHP file and stored in the cache.

$ php symfony cache:clear --type=config

Constants

Configuration files: core_compile.yml, factories.yml, generator.yml, databases.yml, filters.yml, view.yml, autoload.yml

Some configuration files allow the usage of pre-defined constants. Constants are declared with placeholders using the %XXX% notation (where XXX is an uppercase key) and are replaced by their actual value at "compilation" time.

Configuration Settings

A constant can be any setting defined in the settings.yml configuration file. The placeholder key is then an upper-case setting key name prefixed with SF_:

logging: %SF_LOGGING_ENABLED%

When symfony compiles the configuration file, it replaces all occurrences of the %SF_XXX% placeholders by their value from settings.yml. In the above example, it will replace the SF_LOGGING_ENABLED placeholder with the value of the logging_enabled setting defined in settings.yml.

Application Settings

You can also use settings defined in the app.yml configuration file by prefixing the key name with APP_.

Special Constants

By default, symfony defines four constants according to the current front controller:

Directories

Constants are also very useful when you need to reference a directory or a file path without hardcoding it. Symfony defines a number of constants for common project and application directories.

At the root of the hierarchy is the project root directory, SF_ROOT_DIR. All other constants are derived from this root directory.

The project directory structure is defined as follows:

The application directory structure is defined under the SF_APPS_DIR/APP_NAME directory:

Eventually, the application cache directory structure is defined as follows:

environment-awareness

Configuration files: settings.yml, factories.yml, databases.yml, app.yml

Some symfony configuration files are environment-aware -- their interpretation depends on the current symfony environment. These files have different sections that define the configuration should vary for each environment. When creating a new application, symfony creates sensible configuration for the three default symfony environments: prod, test, and dev:

prod:
  # Configuration for the `prod` environment
 
test:
  # Configuration for the `test` environment
 
dev:
  # Configuration for the `dev` environment
 
all:
  # Default configuration for all environments

When symfony needs a value from a configuration file, it merges the configuration found in the current environment section with the all configuration. The special all section describes the default configuration for all environments. If the environment section is not defined, symfony falls back to the all configuration.

Configuration Cascade

Configuration files: core_compile.yml, autoload.yml, settings.yml, factories.yml, databases.yml, security.yml, cache.yml, app.yml, filters.yml, view.yml

Some configuration files can be defined in several config/ sub-directories contained in the project directory structure.

When the configuration is compiled, the values from all the different files are merged according to a precedence order:

• The module configuration (PROJECT_ROOT_DIR/apps/APP_NAME/modules/MODULE_NAME/config/XXX.yml)
• The application configuration (PROJECT_ROOT_DIR/apps/APP_NAME/config/XXX.yml)
• The project configuration (PROJECT_ROOT_DIR/config/XXX.yml)
• The configuration defined in the plugins (PROJECT_ROOT_DIR/plugins/*/config/XXX.yml)
• The default configuration defined in the symfony libraries (SF_LIB_DIR/config/XXX.yml)

For instance, the settings.yml defined in an application directory inherits from the configuration set in the main config/ directory of the project, and eventually from the default configuration contained in the framework itself (lib/config/config/settings.yml).