Caution: You are browsing the legacy 1.x part of this website.
This version of symfony is not maintained anymore. If some of your projects still use this version, consider upgrading.
This work is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License license.

Master Symfony2 fundamentals

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).
trainings.sensiolabs.com

Discover the SensioLabs Support

Access to the SensioLabs Competency Center for an exclusive and tailor-made support on Symfony
sensiolabs.com
Blackfire Profiler Fire up your PHP Apps Performance

PHP Project Quality Done Right

Configuration File Principles

The Reference Book
Support symfony!
Buy this book
or donate.
Buy The Reference Book from amazon.com

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.

tip

In the dev environment, where is_debug is set to true by default, the compilation is done whenever the configuration file changes (symfony checks the file modification 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.

tip

To force the configuration cache to be reloaded, you can use the cache:clear task:

$ 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:

Constant Description Configuration method
SF_APP The current application name getApplication()
SF_ENVIRONMENT The current environment name getEnvironment()
SF_DEBUG Whether debug is enabled or not isDebug()
SF_SYMFONY_LIB_DIR The symfony libraries directory getSymfonyLibDir()

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:

Constants Default Value
SF_APPS_DIR SF_ROOT_DIR/apps
SF_CONFIG_DIR SF_ROOT_DIR/config
SF_CACHE_DIR SF_ROOT_DIR/cache
SF_DATA_DIR SF_ROOT_DIR/data
SF_DOC_DIR SF_ROOT_DIR/doc
SF_LIB_DIR SF_ROOT_DIR/lib
SF_LOG_DIR SF_ROOT_DIR/log
SF_PLUGINS_DIR SF_ROOT_DIR/plugins
SF_TEST_DIR SF_ROOT_DIR/test
SF_WEB_DIR SF_ROOT_DIR/web
SF_UPLOAD_DIR SF_WEB_DIR/uploads

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

Constants Default Value
SF_APP_CONFIG_DIR SF_APP_DIR/config
SF_APP_LIB_DIR SF_APP_DIR/lib
SF_APP_MODULE_DIR SF_APP_DIR/modules
SF_APP_TEMPLATE_DIR SF_APP_DIR/templates
SF_APP_I18N_DIR SF_APP_DIR/i18n

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

Constants Default Value
SF_APP_BASE_CACHE_DIR SF_CACHE_DIR/APP_NAME
SF_APP_CACHE_DIR SF_CACHE_DIR/APP_NAME/ENV_NAME
SF_TEMPLATE_CACHE_DIR SF_APP_CACHE_DIR/template
SF_I18N_CACHE_DIR SF_APP_CACHE_DIR/i18n
SF_CONFIG_CACHE_DIR SF_APP_CACHE_DIR/config
SF_TEST_CACHE_DIR SF_APP_CACHE_DIR/test
SF_MODULE_CACHE_DIR SF_APP_CACHE_DIR/modules

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).

tip

When a configuration file is environment-aware and can be defined in several directories, the following priority list applies:

  1. Module
  2. Application
  3. Project
  4. Specific environment
  5. All environments
  6. Default