The definitive guide of Symfony 1.0

5.5. Accessing the Configuration from Code

All the configuration files are eventually transformed into PHP, and many of the settings they contain are automatically used by the framework, without further intervention. However, you sometimes need to access some of the settings defined in the configuration files from your code (in actions, templates, custom classes, and so on). The settings defined in settings.yml, app.yml, module.yml, logging.yml, and i18n.yml are available through a special class called sfConfig.

5.5.1. The sfConfig Class

You can access settings from within the application code through the sfConfig class. It is a registry for configuration parameters, with a simple getter class method, accessible from every part of the code:

// Retrieve a setting
parameter = sfConfig::get('param_name', $default_value);

Note that you can also define, or override, a setting from within PHP code:

// Define a setting
sfConfig::set('param_name', $value);

The parameter name is the concatenation of several elements, separated by underscores, in this order:

  • A prefix related to the configuration file name (sf_ for settings.yml, app_ for app.yml, mod_ for module.yml, sf_i18n_ for i18n.yml, and sf_logging_ for logging.yml)
  • The parent keys (if defined), in lowercase
  • The name of the key, in lowercase

The environment is not included, since your PHP code will have access only to the values defined for the environment in which it's executed.

For instance, if you need to access the values defined in the app.yml file shown in Listing 5-15, you will need the code shown in Listing 5-16.

Listing 5-15 - Sample app.yml Configuration

all:
  .general:
    tax:          19.6
  default_user:
    name:         John Doe
  mail:
    webmaster:    [email protected]
    contact:      [email protected]
dev:
  mail:
    webmaster:    [email protected]
    contact:      [email protected]

Listing 5-16 - Accessing Configuration Settings in PHP in the dev Environment

echo sfConfig::get('app_tax');   // Remember that category headers are ignored
 => '19.6'
echo sfConfig::get('app_default_user_name');
 => 'John Doe'
echo sfConfig::get('app_mail_webmaster');
 => '[email protected]'
echo sfConfig::get('app_mail_contact');
 => '[email protected]'

So symfony configuration settings have all the advantages of PHP constants, but without the disadvantages, since the value can be changed.

On that account, the settings.yml file, where you can set the framework settings for an application, is the equivalent to a list of sfConfig::set() calls. Listing 5-17 is interpreted as shown in Listing 5-18.

Listing 5-17 - Extract of settings.yml

all:
  .settings:
    available:              on
    path_info_array:        SERVER
    path_info_key:          PATH_INFO
    url_format:             PATH

Listing 5-18 - What Symfony Does When Parsing settings.yml

sfConfig::add(array(
  'sf_available' => true,
  'sf_path_info_array' => 'SERVER',
  'sf_path_info_key' => 'PATH_INFO',
  'sf_url_format' => 'PATH',
));

Refer to Chapter 19 for the meanings of the settings found in the settings.yml file.

5.5.2. Custom Application Settings and app.yml

Most of the settings related to the features of an application should be stored in the app.yml file, located in the myproject/apps/myapp/config/ directory. This file is environment-dependent and empty by default. Put in every setting that you want to be easily changed, and use the sfConfig class to access these settings from your code. Listing 5-19 shows an example.

Listing 5-19 - Sample app.yml to Define Credit Card Operators Accepted for a Given Site

all:
  creditcards:
    fake:             off
    visa:             on
    americanexpress:  on

dev:
  creditcards:
    fake:             on

To know if the fake credit cards are accepted in the current environment, get the value of:

sfConfig::get('app_creditcards_fake');

Note When you should require an PHP array directly beneath the all key you need to use a category header, otherwise symfony will make the values separately available as shown above.

all:
  .array:
    creditcards:
      fake:             off
      visa:             on
      americanexpress:  on
print_r(sfConfig::get('app_creditcards'));

Array(
    [fake] => false
    [visa] => true
    [americanexpress] => true
)

Tip Each time you are tempted to define a constant or a setting in one of your scripts, think about if it would be better located in the app.yml file. This is a very convenient place to store all application settings.

When your need for custom parameters becomes hard to handle with the app.yml syntax, you may need to define a syntax of your own. In that case, you can store the configuration in a new file, interpreted by a new configuration handler. Refer to Chapter 19 for more information about configuration handlers.