Caution: You are browsing the legacy symfony 1.x part of this website.

The settings.yml Configuration File

Symfony version
Language

Most aspects of symfony can be configured either via a configuration file written in YAML, or with plain PHP. In this section, the main configuration file for an application, settings.yml, will be described.

The main settings.yml configuration file for an application can be found in the apps/APP_NAME/config/ directory.

As discussed in the introduction, the settings.yml file is environment-aware, and benefits from the configuration cascade mechanism.

Each environment section has two sub-sections: .actions and .settings. All configuration directives go under the .settings sub-section, except for the default actions to be rendered for some common pages.

note

The settings.yml configuration file is cached as a PHP file; the process is automatically managed by the sfDefineEnvironmentConfigHandler class.

Settings

The .actions Sub-Section

Default configuration:

default:
  .actions:
    error_404_module:       default
    error_404_action:       error404
 
    login_module:           default
    login_action:           login
 
    secure_module:          default
    secure_action:          secure
 
    module_disabled_module: default
    module_disabled_action: disabled

The .actions sub-section defines the action to execute when common pages must be rendered. Each definition has two components: one for the module (suffixed by _module), and one for the action (suffixed by _action).

error_404

The error_404 action is executed when a 404 page must be rendered.

login

The login action is executed when a non-authenticated user tries to access a secure page.

secure

The secure action is executed when a user doesn't have the required credentials.

module_disabled

The module_disabled action is executed when a user requests a disabled module.

The .settings Sub-Section

The .settings sub-section is where the framework configuration occurs. The paragraphs below describe all possible settings and are roughly ordered by importance.

All settings defined in the .settings section are available anywhere in the code by using the sfConfig object and prefixing the setting with sf_. For instance, to get the value of the charset setting, use:

sfConfig::get('sf_charset');

escaping_strategy

Default: off

The escaping_strategy setting is a Boolean setting that determines if the output escaper sub-framework is enabled. When enabled, all variables made available in the templates are automatically escaped by calling the helper function defined by the escaping_method setting (see below).

Be careful that the escaping_method is the default helper used by symfony, but this can be overridden on a case by case basis, when outputting a variable in a JavaScript script tag for example.

The output escaper sub-framework uses the charset setting for the escaping.

It is highly recommended to change the default value to on.

tip

This settings can be set when you create an application with the generate:app task by using the --escaping-strategy option.

escaping_method

Default: ESC_SPECIALCHARS

The escaping_method defines the default function to use for escaping variables in templates (see the escaping_strategy setting above).

You can choose one of the built-in values: ESC_SPECIALCHARS, ESC_RAW, ESC_ENTITIES, ESC_JS, ESC_JS_NO_ENTITIES, and ESC_SPECIALCHARS, or create your own function.

Most of the time, the default value is fine. The ESC_ENTITIES helper can also be used, especially if you are only working with English or European languages.

csrf_secret

Default: false

The csrf_secret is a unique secret for your application. If not set to false, it enables CSRF protection for all forms defined with the form framework. This settings is also used by the link_to() helper when it needs to convert a link to a form (to simulate a DELETE HTTP method for example).

It is highly recommended to change the default value to a unique secret.

tip

This settings can be set when you create an application with the generate:app task by using the --csrf-secret option.

charset

Default: utf-8

The charset setting is the charset that will be used everywhere in the framework: from the response Content-Type header, to the output escaping feature.

Most of the time, the default is fine.

warning

This setting is used in many different places in the framework, and so its value is cached in several places. After changing it, the configuration cache must be cleared, even in the development environment.

enabled_modules

Default: [default]

The enabled_modules is an array of module names to enable for this application. Modules defined in plugins or in the symfony core are not enabled by default, and must be listed in this setting to be accessible.

Adding a module is as simple as appending it to the list (the order of the modules do not matter):

enabled_modules: [default, sfGuardAuth]

The default module defined in the framework contains all the default actions set in the .actions sub-section of settings.yml. It is recommended that you customize all of them, and then remove the default module from this setting.

default_timezone

Default: none

The default_timezone setting defines the default timezone used by PHP. It can be any timezone recognized by PHP.

note

If you don't define a timezone, you are advised to define one in the php.ini file. If not, symfony will try to guess the best timezone by calling the date_default_timezone_get() PHP function.

cache

Default: off

The cache setting enables or disables template caching.

tip

The general configuration of the cache system is done in the view_cache_manager and view_cache sections of the factories.yml configuration file. The fined-grained configuration is done in the cache.yml configuration file.

etag

Default: on by default except for the dev and test environments

The etag setting enables or disables the automatic generation of ETag HTTP headers. The ETag generated by symfony is a simple md5 of the response content.

i18n

Default: off

The i18n setting is a Boolean that enables or disables the i18n sub-framework. If your application is internationalized, set it to on.

tip

The general configuration of the i18n system is to be done in the i18n section of the factories.yml configuration file.

default_culture

Default: en

The default_culture setting defines the default culture used by the i18n sub-framework. It can be any valid culture.

standard_helpers

Default: [Partial, Cache, Form]

The standard_helpers setting is an array of helper groups to load for all templates (name of the group helper without the Helper suffix).

no_script_name

Default: on for the prod environment of the first application created, off for all others

The no_script_name setting determines whether the front controller script name is prepended to generated URLs or not. By default, it is set to on by the generate:app task for the prod environment of the first application created.

Obviously, only one application and environment can have this setting set to on if all front controllers are in the same directory (web/). If you want more than one application with no_script_name set to on, move the corresponding front controller(s) under a sub-directory of the web root directory.

lazy_cache_key

Default: on for new projects, off for upgraded projects

When enabled, the lazy_cache_key setting delays the creation of a cache key until after checking whether an action or partial is cacheable. This can result in a big performance improvement, depending on your usage of template partials.

This setting was introduced in symfony 1.2.7 to improve performance without breaking backward compatibility with previous 1.2 releases. It will be removed in symfony 1.3 as the optimization will always be enabled.

caution

This setting is only available for symfony 1.2.7 and up.

logging_enabled

Default: on for all environments except prod

The logging_enabled setting enables the logging sub-framework. Setting it to false bypasses the logging mechanism completely and provides a small performance gain.

tip

The fined-grained configuration of the logging is to be done in the factories.yml configuration file.

web_debug

Default: off for all environments except dev

The web_debug setting enables the web debug toolbar. The web debug toolbar is injected into a page when the response content type is HTML.

error_reporting

Default:

  • prod: E_PARSE | E_COMPILE_ERROR | E_ERROR | E_CORE_ERROR | E_USER_ERROR
  • dev: E_ALL | E_STRICT
  • test: (E_ALL | E_STRICT) ^ E_NOTICE
  • default: E_PARSE | E_COMPILE_ERROR | E_ERROR | E_CORE_ERROR | E_USER_ERROR

The error_reporting setting controls the level of PHP error reporting (to be displayed in the browser and written to the logs).

tip

The PHP website has some information about how to use bitwise operators.

The default configuration is the most sensible one, and should not be altered.

note

The display of errors in the browser is automatically disabled for front controllers that have debug disabled, which is the case by default for the prod environment.

compressed

Default: off

The compressed setting enables native PHP response compression. If set to on, symfony will use ob_gzhandler as a callback function for ob_start().

It is recommended to keep it to off, and use the native compression mechanism of your web server instead.

use_database

Default: on

The use_database determines if the application uses a database or not.

check_lock

Default: off

The check_lock setting enables or disables the application lock system triggered by some tasks like cache:clear and project:disable.

If set to on, all requests to disabled applications are automatically redirected to the symfony core lib/exception/data/unavailable.php page.

tip

You can override the default unavailable template by adding a config/unavailable.php file to your project or application.

check_symfony_version

Default: off

The check_symfony_version enables or disables checking of the current symfony version upon every request. If enabled, symfony will clear the cache automatically when the framework is upgraded.

It is highly recommended to not set this to on as it adds a small overhead, and because it is simple to just clear the cache when you deploy a new version of your project. This setting is only useful if several projects share the same symfony code, which is not recommended.

web_debug_web_dir

Default: /sf/sf_web_debug

The web_debug_web_dir sets the web path to the web debug toolbar assets (images, stylesheets, and JavaScript files).

strip_comments

Default: on

The strip_comments determines if symfony should strip the comments when compiling core classes. This setting is only used if the application debug setting is set to off.

If you have blank pages in the production environment only, try to set this setting to off.

max_forwards

Default: 5

The max_forwards setting sets the maximum number of internal forwards allowed before symfony throws an exception. This is to avoid infinite loops.

This work is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License license.