5.2. Overview of the Configuration Files (The definitive guide of Symfony 1.0)

Configuration is distributed into files, by subject. The files contain parameter definitions, or settings. Some of these parameters can be overridden at several levels (project, application, and module); some are specific to a certain level. The next chapters will deal with the configuration files related to their main topic, and Chapter 19 will deal with advanced configuration.

5.2.1. Project Configuration

There are a few project configuration files by default. Here are the files that can be found in the myproject/config/ directory:

config.php: This is the very first file executed by any request or command. It contains the path to the framework files, and you can change it to use a different installation. If you add some define statements at the end of this file, the constants will be accessible from every application of the project. See Chapter 19 for advanced usage of this file.
databases.yml: This is where you define the access and connection settings to the database (host, login, password, database name, and so on). Chapter 8 will tell you more about it. It can also be overridden at the application level.
properties.ini: This file holds a few parameters used by the command line tool, including the project name and the connection settings for distant servers. See Chapter 16 for an overview of the features using this file.
rsync_exclude.txt: This file specifies which directories must be excluded from the synchronization between servers. It is discussed in Chapter 16.
schema.yml and propel.ini: These are data access configuration files used by Propel (symfony's ORM layer). They are used to make the Propel libraries work with the symfony classes and the data of your project. schema.yml contains a representation of the project's relational data model. propel.ini is automatically generated, so you probably do not need to modify it. If you don't use Propel, these files are not needed. Chapter 8 will tell you more about their use.

These files are mostly used by external components or by the command line, or they need to be processed even before any YAML parsing program can be loaded by the framework. That's why some of them don't use the YAML format.

5.2.2. Application Configuration

The main part of the configuration is the application configuration. It is defined in the front controller (in the web/ directory) for the main constants, in YAML files located in the application config/ directory, in i18n/ directories for the internationalization files, and in the framework files for invisible — although useful — additional application configuration.

5.2.2.1. Front Controller Configuration

The very first application configuration is actually found in the front controller; that is the very first script executed by a request. Take a look at the default web/index.php in Listing 5-11.

Listing 5-11 - The Default Production Front Controller

<?php

define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/..'));
define('SF_APP',         'myapp');
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       false);

require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');

sfContext::getInstance()->getController()->dispatch();

After defining the name of the application (myapp) and the environment (prod), the general configuration file is called before the dispatching. So a few useful constants are defined here:

SF_ROOT_DIR: Project root directory (normally, should remain at its default value, unless you change the file structure).
SF_APP: Application name in the project. Necessary to compute file paths.
SF_ENVIRONMENT: Environment name (prod, dev, or any other project-specific environment that you define). Will determine which configuration settings are to be used. Environments are explained later in this chapter.
SF_DEBUG: Activation of the debug mode (see Chapter 16 for details).

If you want to change one of these values, you probably need an additional front controller. The next chapter will tell you more about front controllers and how to create a new one.

The root directory can be anywhere Only the files and scripts located under the web root (the web/ directory in a symfony project) are available from the outside. The front controller scripts, images, style sheets, and JavaScript files are public. All the other files must be outside the server web root--that means they can be anywhere else.

The non-public files of a project are accessed by the front controller from the SF_ROOT_DIR path. Classically, the root directory is one level up the web/ directory. But you can choose a completely different structure. Imagine that your main directory structure is made of two directories, one public and one private:

symfony/    # Private area
    apps/
    batch/
    cache/
    ...
www/        # Public area
    images/
    css/
    js/
    index.php

In this case, the root directory is the symfony/ directory. So the index.php front controller simply needs to define the SF_ROOT_DIR as follows for the application to work:

define('SF_ROOT_DIR', dirname(__FILE__).'/../symfony');

Chapter 19 will give you more information about how to tweak symfony to make it work on a specific directory structure.

5.2.2.2. Main Application Configuration

The main application configuration is stored in files located in the myproject/apps/myapp/config/ directory:

app.yml: This file should contain the application-specific configuration; that is, global variables defining business or applicative logic specific to an application, which don't need to be stored in a database. Tax rates, shipping fares, and e-mail addresses are often stored in this file. It is empty by default.
config.php: This file bootstraps the application, which means that it does all the very basic initializations to allow the application to start. This is where you can customize your directory structure or add application-specific constants (Chapter 19 provides more details). It starts by including the project's config.php.
factories.yml: Symfony defines its own class to handle the view, the request, the response, the session, and so on. If you want to use your own classes instead, this is where you can specify them. Chapter 17 provides more information.
filters.yml: Filters are portions of code executed for every request. This file is where you define which filters are to be processed, and it can be overridden for each module. Chapter 6 discusses filters in more detail.
logging.yml: This file defines which level of detail must be recorded in the logs, to help you manage and debug your application. The use of this configuration is explained in Chapter 16.
routing.yml: The routing rules, which allow transforming unreadable and unbookmarkable URLs into "smart" and explicit ones, are stored in this file. For new applications, a few default rules exist. Chapter 9 is all about links and routing.
settings.yml: The main settings of a symfony application are defined in this file. This is where you specify if your application has internationalization, its default language, the request timeout and whether caching is turned on. With a one-line change in this file, you can shut down the application so you can perform maintenance or upgrade one of its components. The common settings and their use are described in Chapter 19.
view.yml: The structure of the default view (name of the layout, title, and meta tags; default style sheets and JavaScript files to be included; default content-type, and so on) is set in this file. It also defines the default value of the meta and title tags. Chapter 7 will tell you more about this file. These settings can be overridden for each module.

5.2.2.3. Internationalization Configuration

Internationalized applications can display pages in several languages. This requires specific configuration. There are two configuration places for internationalization:

i18n.yml of the application config/ directory: This file defines general translation settings, such as the default culture for the translation, whether the translations come from files or a database, and their format.
Translation files in the application i18n/ directory: These are basically dictionaries, giving a translation for each of the phrases used in the application templates so that the pages show translated text when the user switches language.

Note that the activation of the i18n features is set in the settings.yml file. You will find more information about these features in Chapter 13.

5.2.2.4. Additional Application Configuration

A second set of configuration files is in the symfony installation directory (in $sf_symfony_ data_dir/config/) and doesn't appear in the configuration directory of your applications. The settings defined there are defaults that seldom need to be modified, or that are global to all projects. However, if you need to modify them, just create an empty file with the same name in your myproject/apps/myapp/config/ directory, and override the settings you want to change. The settings defined in an application always have precedence over the ones defined in the framework. The following are the configuration files in the symfony installation config/ directory:

autoload.yml: This file contains the settings of the autoloading feature. This feature exempts you from requiring custom classes in your code if they are located in specific directories. It is described in detail in Chapter 19.
constants.php: This file contains the default application file structure. To override the settings of this file, use the application config.php, as explained in Chapter 19.
core_compile.yml and bootstrap_compile.yml: These are lists of classes to be included to start an application (in bootstrap_compile.yml) and to process a request (in core_compile.yml). These classes are actually concatenated into an optimized PHP file without comments, which will accelerate the execution by minimizing the file access operations (one file is loaded instead of more than forty for each request). This is especially useful if you don't use a PHP accelerator. Optimization techniques are described in Chapter 18.
config_handlers.yml: This is where you can add or modify the handlers used to process each configuration file. Chapter 19 provides more details.
php.yml: This file checks that the variables of the php.ini file are properly defined and allows you to override them, if necessary. Check Chapter 19 for details.

5.2.3. Module Configuration

By default, a module has no specific configuration. But, if required, you can override some application-level settings for a given module. For instance, you might do this to change the HTML description of all the actions of a module, or to include a specific JavaScript file. You can also choose to add new parameters restricted to a specific module to preserve encapsulation.

As you may have guessed, module configuration files must be located in a myproject/apps/myapp/modules/mymodule/config/ directory. These files are as follows:

generator.yml: For modules generated according to a database table (scaffoldings and administrations), this file defines how the interface displays rows and fields, and which interactions are proposed to the user (filters, sorting, buttons, and so on). Chapter 14 will tell you more about it.
module.yml: This file contains custom parameters specific to a module (equivalent to the app.yml, but at the module level) and action configuration. Chapter 6 provides more details.
security.yml: This file sets access restrictions for actions. This is where you specify that a page can be viewed only by registered users or by a subset of registered users with special permissions. Chapter 6 will tell you more about it.
view.yml: This file contains configuration for the views of one or all of the actions of a module. It overrides the application view.yml and is described in Chapter 7.
Data validation files: Although located in the validate/ directory instead of the config/ one, the YAML data validation files, used to control the data entered in forms, are also module configuration files. You will learn how to use them in Chapter 10.

Most module configuration files offer the ability to define parameters for all the views or all the actions of a module, or for a subset of them.

Too many files? You might be overwhelmed by the number of configuration files present in the application. But please keep the following in mind:

Most of the time, you don't need to change the configuration, since the default conventions match the most common requirements. Each configuration file is related to a particular feature, and the next chapters will detail their use one by one. When you focus on a single file, you can see clearly what it does and how it is organized. For professional web development, the default configuration is often not completely adapted. The configuration files allow for an easy modification of the symfony mechanisms without code. Imagine the amount of PHP code necessary to achieve the same amount of control. If all the configuration were located in one file, not only would the file be completely unreadable, but you could not redefine configuration at several levels (see the "Configuration Cascade" section later in this chapter).

The configuration system is one of the great strengths of symfony, because it makes symfony usable for almost every kind of web application, and not only for the ones for which the framework was originally designed.