19.1. Symfony Settings

The frontend/config/settings.yml file contains the main symfony configuration for the frontend 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

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_lib_dir/controller/default/ directory. The settings.yml file defines which action is executed depending on the error:

• error_404_module and error_404_action: Action called when the URL entered by the user doesn't match any route or when an sfError404Exception occurs. The default value is default/error404.
• login_module and login_action: Action called when a nonauthenticated user tries to access a page defined as secure in security.yml (see Chapter 6 for details). The default value is default/login.
• secure_module and secure_action: Action called when a user doesn't have the credentials required for an action. The default value is default/secure.
• module_disabled_module and module_disabled_action: Action called when a user requests a module declared as disabled in module.yml. The default value is default/disabled.

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.

Figure 19.1 Default 404 error 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 the settings.yml file (index, error404, login, secure, disabled) and all the related templates (indexSuccess.php, error404Success.php, loginSuccess.php, secureSuccess.php, disabledSuccess.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_lib_dir/exception/data/ directory:

• error.html.php: Page called when an internal server error occurs in the production environment. In other environments (where debug is set to true), when an error occurs, symfony display
• unavailable.php: Page called when a user requests a page while the application is disabled (with the disable task). It is also called while the cache is being cleared (that is, between a call to the php symfony cache:clear 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 error.html.php and unavailable.php pages in your project or application's config/error/ directory. Symfony will use these instead of its own.

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

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 value on, or off.
• The escaping_method setting can be set to ESC_RAW, ESC_SPECIALCHARS, ESC_ENTITIES, ESC_JS, or ESC_JS_NO_ENTITIES.

19.1.3.2. Routing Settings ###

The routing settings (see Chapter 9) are defined in factories.yml, under the routing key. Listing 19-1 show the default routing configuration.

Listing 19-1 - Routing Configuration Settings, in frontend/config/factories.yml

routing:
  class: sfPatternRouting
  param:
    load_configuration: true
    suffix:             .
    default_module:     default
    default_action:     index
    variable_prefixes:  [':']
    segment_separators: ['/', '.']
    variable_regex:     '[\w\d_]+'
    debug:              %SF_DEBUG%
    logging:            %SF_LOGGING_ENABLED%
    cache:
      class: sfFileCache
      param:
        automatic_cleaning_factor: 0
        cache_dir:                 %SF_CONFIG_CACHE_DIR%/routing
        lifetime:                  31556926
        prefix:                    %SF_APP_DIR%

• 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.
• When a routing rule doesn't define the module or the action parameter, values from the factories.yml are used instead:
  • default_module: Default module request parameter. Defaults to the default module.
  • default_action: Default action request parameter. Defaults to the index action.
• By default, route patterns identify named wildcards by a colon (:) prefix. But if you want to write your rules in a more PHP-friendly syntax, you can add the dollar ($) sign in the variable_prefixes array. That way, you can write a pattern like '/article/$year/$month/$day/$title' instead of '/article/:year/:month/:day/:title'.
• The pattern routing will identify named wildcards between separators. The default separators are the slash and the dot, but you can add more if you want in the segment_separators parameter. For instance, if you add the dash (-), you can write a pattern like '/article/:year-:month-:day/:title'.
• The pattern routing uses its own cache, in production mode, to speed up conversions between external URLs and internal URIs. By default, this cache uses the filesystem, but you can use any cache class, provided that you declare the class and its settings in the cache parameter. See Chapter 15 for the list of available cache storage classes. To deactivate the routing cache in production, set the debug parameter to on.

These are only the settings for the sfPatternRouting class. You can use another class for your application routing, either your own or one of symfony's routing factories (sfNoRouting and sfPathInfoRouting). With either of these two factories, all external URLs look like 'module/action?key1=param1'. No customization possible — but it's fast. The difference is that the first uses PHP's GET, and the second uses PATH_INFO. Use them mainly for backend interfaces.

There is one additional parameter related to routing, but this one is stored in settings.yml:

• no_script_name enables the front controller name in generated URLs. The no_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). You can also specify which storage to use for two all cache systems (the view cache, the routing cache, and the i18n cache) in factories.yml. Listing 19-2 show the default view cache factory configuration.

Listing 19-2 - View Cache Configuration Settings, in frontend/config/factories.yml

view_cache:
  class: sfFileCache
  param:
    automatic_cleaning_factor: 0
    cache_dir:                 %SF_TEMPLATE_CACHE_DIR%
    lifetime:                  86400
    prefix:                    %SF_APP_DIR%/template

The class can be any of sfFileCache, sfAPCCache, sfEAcceleratorCache, sfXCacheCache, sfMemcacheCache, and sfSQLiteCache. It can also be your own custom class, provided it extends sfCache and provides the same generic methods for setting, retrieving and deleting a key in the cache. The factory parameters depend on the class you choose, but there are constants:

• lifetime defines the number of seconds after which a cache part is removed
• prefix is a prefix added to every cache key (use the environment in the prefix to use different cache depending on the environment). Use the same prefix for two applications if you want their cache to be shared.

Then, for each particular factory, you have to define the location of the cache storage.

• for sfFileCache, the cache_dir parameter locates the absolute path to the cache directory
• sfAPCCache, sfEAcceleratorCache, and sfXCacheCache don't take any location parameter, since they use PHP native functions for communicating with APC, EAccelerator or the XCache cache systems
• for sfMemcacheCache, enter the hostname of the Memcached server in the host parameter, or an array of hosts in the servers parameter
• for sfSQLiteCache, the absolute path to the SQLite database file should be entered in the database parameter

For additional parameters, check the API documentation of each cache class.

The view is not the only component to be able to use a cache. Both the routing and the I18N factories offer a cache parameter in which you can set any cache factory, just like the view cache. For instance, Listing 19-1 shows of the routing uses the file cache for its speedup tactics by default, but you can change it to whatever you want.

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 E_PARSE | E_COMPILE_ERROR | E_ERROR | E_CORE_ERROR | E_USER_ERROR for the production environment (so the logged events are E_PARSE, E_COMPILE_ERROR, E_ERROR, E_CORE_ERROR, and E_USER_ERROR) and to E_ALL | E_STRICT for the development environment.
• The web_debug setting activates the web debug toolbar. Set it to on 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-3 lists them as they appear in the configuration file.

Listing 19-3 - Miscellaneous Configuration Settings, in frontend/config/settings.yml

# Remove comments in core framework classes as defined in the core_compile.yml
strip_comments:         on
# Maximum number of forwards followed by the action before raising an exception
max_forwards:           5

all:
  creditcards:
    fake:             off    # app_creditcards_fake
    visa:             on     # app_creditcards_visa
    americanexpress:  on     # app_creditcards_americanexpress