The myapp/config/settings.yml
file contains the main symfony configuration for the myapp
application. You have already seen the function of many settings from this file in the previous chapters, but let's revisit them.
As explained in Chapter 5, this file is environment-dependent, which means that each setting can take a different value for each environment. Remember that each parameter defined in this file is accessible from inside the PHP code via the sfConfig
class. The parameter name is the setting name prefixed with sf_
. For instance, if you want to get the value of the cache
parameter, you just need to call sfConfig::get('sf_cache')
.
19.1.1. Default Modules and Actions
When a routing rule doesn't define the module
or the action
parameter, values from the settings.yml
file are used instead:
default_module
: Defaultmodule
request parameter. Defaults to thedefault
module.default_action
: Defaultaction
request parameter. Defaults to theindex
action.
Symfony provides default pages for special situations. In the case of a routing error, symfony executes an action of the default
module, which is stored in the $sf_symfony_data_dir/modules/default/
directory. The settings.yml
file defines which action is executed depending on the error:
error_404_module
anderror_404_action
: Action called when the URL entered by the user doesn't match any route or when ansfError404Exception
occurs. The default value isdefault/error404
.login_module
andlogin_action
: Action called when a nonauthenticated user tries to access a page defined assecure
insecurity.yml
(see Chapter 6 for details). The default value isdefault/login
.secure_module
andsecure_action
: Action called when a user doesn't have the credentials required for an action. The default value isdefault/secure
.module_disabled_module
andmodule_disabled_action
: Action called when a user requests a module declared as disabled inmodule.yml
. The default value isdefault/disabled
.unavailable_module
andunavailable_action
: Action called when a user requests a page from a disabled application. The default value isdefault/unavailable
. To disable an application, set theavailable
parameter tooff
insettings.yml
.
Before deploying an application to production, you should customize these actions, because the default
module templates include the symfony logo on the page. See Figure 19-1 for a screenshot of one of these pages, the error 404 page.
You can override the default pages in two ways:
- You can create your own default module in the application's
modules/
directory, override all the actions defined in thesettings.yml
file (index
,error404
,login
,secure
,disabled
, andunavailable
) and all the related templates (indexSuccess.php
,error404Success.php
,loginSuccess.php
,secureSuccess.php
,disabledSuccess.php
, andunavailableSuccess.php
). - You can change the default module and action settings of the
settings.yml
file to use pages of your application.
Two other pages bear a symfony look and feel, and they also need to be customized before deployment to production. These pages are not in the default
module, because they are called when symfony cannot run properly. Instead, you will find these default pages in the $sf_symfony_data_dir/web/errors/
directory:
error500.php
: Page called when an internal server error occurs in the production environment. In other environments (whereSF_DEBUG
is set totrue
), when an error occurs, symfony displays the full execution stack and an explicit error message (see Chapter 16 for details).unavailable.php
: Page called when a user requests a page while the cache is being cleared (that is, between a call to thesymfony clear-cache
task and the end of this task execution). On systems with a very large cache, the cache-clearing process can take several seconds. Symfony cannot execute a request with a partially cleared cache, so requests received before the end of the process are redirected to this page.
To customize these pages, simply create error500.php
and unavailable.php
pages in your application's web/errors/
directory. Symfony will use these instead of its own.
Note To have requests redirected to the unavailable.php
page when needed, you need to set the check_lock
setting to on
in the application settings.yml
. The check is deactivated by default, because it adds a very slight overhead for every request.
19.1.2. Optional Feature Activation
Some parameters of the settings.yml
file control optional framework features that can be enabled or disabled. Deactivating unused features boosts performances a bit, so make sure to review the settings listed in Table 19-1 before deploying your application.
Table 19-1 - Optional Features Set Through settings.yml
Parameter | Description | Default Value |
---|---|---|
use_database |
Enables the database manager. Set it to off if you don't use a database. |
on |
use_security |
Enables security features (secure actions and credentials; see Chapter 6). The default security filter (sfBasicSecurityFilter ) is enabled only if it is on . |
on |
use_flash |
Enables the flash parameter feature (see Chapter 6). Set it to off if you never use the set_flash() method in your actions. The flash filter (sfFlashFilter ) is enabled only if it is on. |
on |
i18n |
Enables interface translation (see Chapter 13). Set it to on for multilingual applications. |
off |
logging_enabled |
Enables logging of symfony events. Set it to off when you want to ignore the logging.yml settings and turn symfony logging off completely. | on |
escaping_strategy |
Enables and defines the policy of the output escaping feature (see Chapter 7). Set it to off if you don't use the $sf_data container in your templates. |
bc |
cache |
Enables template caching (see Chapter 12). Set it to on if one of your modules includes cache.yml file. The cache filter (sfCacheFilter ) is enabled only if it is on. |
off in development, on in production |
web_debug |
Enables the web debug toolbar for easy debugging (see Chapter 16). Set it to on to display the toolbar on every page. The web debug filter (sfWebDebugFilter ) is enabled only if it is on. |
on in development, off in production |
check_symfony_version |
Enables the check of the symfony version for every request. Set it to on for automatic cache clearing after a framework upgrade. Leave it set to off if you always clear the cache after an upgrade. | off |
check_lock |
Enables the application lock system, triggered by the clear-cache and disable tasks (see the previous section). Set it to on to have all requests to disabled applications redirected to the $sf_symfony_data_dir/web/errors/unavailable.php page. |
off |
compressed |
Enables PHP response compression. Set it to on to compress the outgoing HTML via the PHP compression handler. |
off |
use_process_cache |
Enables symfony optimizations based on PHP accelerators. When such an accelerator (for instance, APC, XCache, or eAccelerator) is installed, symfony takes advantage of its features to keep objects and configuration in memory between requests. Set the parameter to off in development or when you don't want PHP accelerator optimizations. Note that even if you don't have any accelerator installed, leaving it set to on will not harm performance. |
on |
19.1.3. Feature Configuration
Symfony uses some parameters of settings.yml
to alter the behavior of built-in features such as form validation, cache, and third-party modules.
19.1.3.1. Output Escaping Settings
Output escaping settings control the way the variables are accessible in the template (see Chapter 7). The settings.yml
file includes two settings for this feature:
- The
escaping_strategy
setting can take the valuebc
,both
,on
, oroff
. - The escaping_method setting can be set to
ESC_RAW
,ESC_ENTITIES
,ESC_JS
, orESC_JS_NO_ENTITIES
.
19.1.3.2. Routing Settings
Two routing settings (see Chapter 9) are stored in settings.yml
:
- The
suffix
parameter sets the default suffix for generated URLs. The default value is a period (.
), and it corresponds to no suffix. Set it to.html
, for instance, to have all generated URLs look like static pages. - The
no_script_name
parameter enables the front controller name in generated URLs. Theno_script_name
setting can be on only for a single application in a project, unless you store the front controllers in various directories and alter the default URL rewriting rules. It is usually on for the production environment of your main application and off for the others.
19.1.3.3. Form Validation Settings
Form validation settings control the way error messages output by the Validation
helpers look (see Chapter 10). These errors are included in <div>
tags, and they use the validation_error_ class
setting as a class
attribute and the validation_error_id_prefix
setting to build up the id
attribute. The default values are form_error
and error_for_
, so the attributes output by a call to the form_error()
helper for an input named foobar
will be class="form_error" id="error_for_foobar"
.
Two settings determine which characters precede and follow each error message: validation_error_prefix
and validation_error_suffix
. You can change them to customize all error messages at once.
19.1.3.4. Cache Settings
Cache settings are defined in cache.yml
for the most part, except for two in settings.yml
: cache
enables the template cache mechanism, and etag
enables ETag handling on the server side (see Chapter 15).
19.1.3.5. Logging Settings
Two logging settings (see Chapter 16) are stored in settings.yml
:
error_reporting
specifies which events are logged in the PHP logs. By default, it is set to 341 for the production environment (so the logged events areE_PARSE
,E_COMPILE_ERROR
,E_ERROR
,E_CORE_ERROR
, andE_USER_ERROR
) and to 4095 for the development environment (E_ALL
andE_STRICT
).- The
web_debug
setting activates the web debug toolbar. Set it toon
only in the development and test environments.
19.1.3.6. Paths to Assets
The settings.yml
file also stores paths to assets. If you want to use another version of the asset than the one bundled with symfony, you can change these path settings:
- Rich text editor JavaScript files stored in
rich_text_js_dir
(by default,js/tiny_mce
) - Prototype libraries stored in
prototype_web_dir
(by default,/sf/prototype
) - Files needed by the administration generator stored in
admin_web_dir
- Files needed by the web debug toolbar stored in
web_debug_web_dir
- Files needed by the javascript calendar stored in
calendar_web_dir
19.1.3.7. Default Helpers
Default helpers, loaded for every template, are declared in the standard_helpers
setting (see Chapter 7). By default, these are the Partial
, Cache
, and Form
helper groups. If you use a helper group in all templates of an application, adding its name to the standard_helpers
setting saves you the hassle of declaring it with use_helper()
on each template.
19.1.3.8. Activated Modules
Activated modules from plug-ins or from the symfony core are declared in the enabled_modules
parameter. Even if a plug-in bundles a module, users can't request this module unless it is declared in enabled_modules
. The default
module, which provides the default symfony pages (congratulations, page not found, and so on), is the only enabled module by default.
19.1.3.9. Character Set
The character set of the responses is a general setting of the application, because it is used by many components of the framework (templates, output escaper, helpers, and so on). Defined in the charset
setting, its default (and advised) value is utf-8
.
19.1.3.10. Miscellaneous Configuration
The settings.yml
file contains a few more parameters, used internally by symfony for core behaviors. Listing 19-1 lists them as they appear in the configuration file.
Listing 19-1 - Miscellaneous Configuration Settings, in myapp/config/settings.yml
# Remove comments in core framework classes as defined in the core_compile.yml
strip_comments: on
# Functions called when a class is requested and not already loaded
# Expects an array of callables. Used by the framework bridges.
autoloading_functions: ~
# Session timeout, in seconds
timeout: 1800
# Maximum number of forwards followed by the action before raising an exception
max_forwards: 5
# Global constants
path_info_array: SERVER
path_info_key: PATH_INFO
url_format: PATH