Development

Documentation/ja_JP/book/1.0/05-Configuring-Symfony (diff)

You must first sign up to be able to contribute.

Changes from Version 1 of Documentation/ja_JP/book/1.0/05-Configuring-Symfony

Show
Ignore:
Author:
heihachiro (IP: 125.100.73.82)
Timestamp:
02/08/07 12:28:42 (11 years ago)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/ja_JP/book/1.0/05-Configuring-Symfony

    v0 v1  
     1 
     2{{{ 
     3#!WikiMarkdown 
     4Chapter 5 - Configuring Symfony 
     5=============================== 
     6 
     7To be simple and easy to use, symfony defines a few conventions, which should satisfy the most common requirements of standard applications without need for modification. However, using a set of simple and powerful configuration files, it is possible to customize almost everything about the way the framework and your application interact with each other. With these files, you will also be able to add specific parameters for your applications. 
     8 
     9This chapter explains how the configuration system works: 
     10 
     11  * The symfony configuration is kept in files written in YAML, although you can always choose another format. 
     12  * Configuration files are at the project, application, and module levels in a project's directory structure. 
     13  * You can define several sets of configuration settings; in symfony, a set of configuration is called an environment. 
     14  * The values defined in the configuration files are available from the PHP code of your application. 
     15  * Additionally, symfony authorizes PHP code in YAML files and other tricks to make the configuration system even more flexible. 
     16 
     17The Configuration System 
     18------------------------ 
     19 
     20Regardless of purpose, most web applications share a common set of characteristics. For instance, some sections can be restricted to a subset of users, or the pages can be decorated by a layout, or a form can be filled with the user input after a failed validation. A framework defines a structure for emulating these characteristics, and the developer can further tweak them by changing a configuration setting. This strategy saves a lot of development time, since many changes don't require a single line of code, even if there is a lot of code behind. It is also much more efficient, because it ensures such information can be maintained in a single and easily identifiable location. 
     21 
     22However, this approach has two serious drawbacks: 
     23 
     24  * Developers end up writing endlessly complex XML files. 
     25  * In a PHP architecture, every request takes much longer to process. 
     26 
     27Taking these disadvantages into account, symfony uses configuration files only for what they are best at doing. As a matter of fact, the ambition of the configuration system in symfony is to be: 
     28 
     29  * Powerful: Almost every aspect that can be managed using configuration files is managed using configuration files. 
     30  * Simple: Many aspects of configuration are not shown in a normal application, since they seldom need to be changed. 
     31  * Easy: Configuration files are easy to read, to modify, and to create by the developer. 
     32  * Customizable: The default configuration language is YAML, but it can be INI, XML, or whatever format the developer prefers. 
     33  * Fast: The configuration files are never processed by the application but by the configuration system, which compiles them into a fast-processing chunk of code for the PHP server. 
     34 
     35### YAML Syntax and Symfony Conventions 
     36 
     37For its configuration, symfony uses the YAML format by default, instead of more traditional INI or XML formats. YAML shows structure through indentation and is fast to write. Its advantages and basic rules were already described in Chapter 1. However, you need to keep a few conventions in mind when writing YAML files. This section introduces several of the most prominent conventions. For a complete dissertation on the topic, visit the YAML website ((`http://www. yaml.org/`). 
     38 
     39First of all, never use tabs in YAML files; use spaces instead. YAML parsers can't understand files with tabs, so indent your lines with spaces (a double blank is the symfony convention for indentation), as shown in Listing 5-1. 
     40 
     41Listing 5-1 - YAML Files Forbid Tabs 
     42 
     43    # Never use tabs 
     44    all: 
     45    -> mail: 
     46    -> -> webmaster:  webmaster@example.com 
     47 
     48    # Use blanks instead 
     49    all: 
     50      mail: 
     51        webmaster: webmaster@example.com 
     52 
     53If your parameters are strings starting or ending with spaces, enclose the value in single quotes. If a string parameter contains special characters, also enclose the value in single quotes, as shown in Listing 5-2. 
     54 
     55Listing 5-2 - Nonstandard Strings Should Be Enclosed in Single Quotes 
     56 
     57    error1: This field is compulsory 
     58    error2: '  This field is compulsory  ' 
     59    error3: 'Don''t leave this field blank'   # Single quotes must be doubled 
     60 
     61You can define long strings in multiple lines, and also multiple-line strings, with the special string headers (> and |) plus an additional indentation. Listing 5-3 demonstrates this convention. 
     62 
     63Listing 5-3 - Defining Long and Multiline Strings 
     64 
     65    accomplishment: >           # Folded style, introduced by > 
     66      Mark set a major league   # Each line break is folded to a space 
     67      home run record in 1998.  # Makes YAML more readable 
     68    stats: |                    # Literal style, introduced by | 
     69      65 Home Runs              # All line breaks count 
     70      0.278 Batting Average     # Indentation doesn't appear in the resulting string 
     71 
     72To define a value as an array, enclose the elements in square brackets or use the expanded syntax with dashes, as shown in Listing 5-4. 
     73 
     74Listing 5-4 - YAML Array Syntax 
     75 
     76    # Shorthand syntax for arrays 
     77    players: [ Mark McGwire, Sammy Sosa, Ken Griffey ] 
     78 
     79    # Expanded syntax for arrays 
     80    players: 
     81      - Mark McGwire 
     82      - Sammy Sosa 
     83      - Ken Griffey 
     84 
     85To define a value as an associative array, or hash, enclose the elements in curly brackets and always insert a space between the key and the value in the `key: value` couple. You can also use the expanded syntax by adding indentation and a carriage return for every new key, as shown in Listing 5-5. 
     86 
     87Listing 5-5 - YAML Associative Array Syntax 
     88 
     89    # Incorrect syntax, blanks are missing after the colon 
     90    mail: {webmaster:webmaster@example.com,contact:contact@example.com} 
     91 
     92    # Correct shorthand syntax for associative arrays 
     93    mail: { webmaster: webmaster@example.com, contact: contact@example.com } 
     94 
     95    # Expanded syntax for associative arrays 
     96    mail: 
     97      webmaster: webmaster@example.com 
     98      contact:   contact@example.com 
     99 
     100To give a Boolean value, use either `on`, `1`, or `true` for a positive value and `off`, `0`, or `false` for a negative one. Listing 5-6 shows the possible Boolean values. 
     101 
     102Listing 5-6 - YAML Boolean Values Syntax 
     103 
     104    true_values:   [ on, 1, true ] 
     105    false_values:  [ off, 0, false ] 
     106 
     107Don't hesitate to add comments (starting with the hash mark, `#`) and extra spaces to values to make your YAML files more readable, as shown in Listing 5-7. 
     108 
     109Listing 5-7 - YAML Comments Syntax and Value Alignment 
     110 
     111    # This is a comment line 
     112    mail: 
     113      webmaster: webmaster@example.com 
     114      contact:   contact@example.com 
     115      admin:     admin@example.com   # extra spaces allow nice alignment of values 
     116 
     117In some symfony configuration files, you will sometimes see lines that start with a hash mark (and, as such, ignored by the YAML parsers) but look like usual settings lines. This is a symfony convention: the default configuration, inherited from other YAML files located in the symfony core, is repeated in commented lines in your application configuration, for your information. If you want to change the value of such a parameter, you need to uncomment the line first, as shown in Listing 5-8. 
     118 
     119Listing 5-8 - Default Configuration Is Shown Commented 
     120 
     121    # The cache is off by default 
     122    settings: 
     123    # cache: off 
     124 
     125    # If you want to change this setting, uncomment the line first 
     126    settings: 
     127      cache: on 
     128 
     129Symfony sometimes groups the parameter definitions into categories. All settings of a given category appear indented under the category header. Structuring long lists of `key: value` pairs by grouping them into categories improves the readability of the configuration. Category headers start with a dot (`.`). Listing 5-9 shows an example of categories. 
     130 
     131Listing 5-9 - Category Headers Look Like Keys, But Start with a Dot 
     132 
     133    all: 
     134      .general: 
     135        tax:        19.6 
     136 
     137      mail: 
     138        webmaster:  webmaster@example.com 
     139 
     140In this example, `mail` is a key and `general` is only a category header. Everything works as if the category header didn't exist, as shown in Listing 5-10. The `tax` parameter is actually a direct child of the `all` key. 
     141 
     142Listing 5-10 - Category Headers Are Only There for Readability and Are Actually Ignored 
     143 
     144    all: 
     145      tax:          19.6 
     146 
     147      mail: 
     148        webmaster:  webmaster@example.com 
     149 
     150>**SIDEBAR** 
     151>And if you don't like YAML 
     152> 
     153>YAML is just an interface to define settings to be used by PHP code, so the configuration defined in YAML files ends up being transformed into PHP. After browsing an application, check its cached configuration (in `cache/myapp/dev/config/`, for instance). You will see the PHP files corresponding to your YAML configuration. You will learn more about the configuration cache later in this chapter. 
     154> 
     155>The good news is that if you don't want to use YAML files, you can still do what the configuration files do by hand, in PHP or via another format (XML, INT, and so on). Throughout this book, you will meet alternative ways to define configuration without YAML, and you will even learn to replace the symfony configuration handlers (in Chapter 19). If you use them wisely, these tricks will enable you to bypass configuration files or define your own configuration format. 
     156 
     157### Help, a YAML File Killed My App! 
     158 
     159The YAML files are parsed into PHP hashes and arrays, and then the values are used in various parts of the application to modify the behavior of the view, the controller, or the model. Many times, when there is a problem in a YAML file, it is not detected until the value actually needs to be used. Moreover, the error or exception that is thrown then is usually not clearly related to the YAML configuration file. 
     160 
     161If your application suddenly stops working after a configuration change, you should check that you didn't make any of the common mistakes of the inattentive YAML coder: 
     162 
     163  * You miss a space between a key and its value: 
     164 
     165    key1:value1      # A space is missing after the : 
     166 
     167  * Keys in a sequence are not indented the same way: 
     168 
     169    all: 
     170      key1:  value1 
     171       key2: value2  # Indentation is not the same as the other sequence members 
     172      key3:  value3 
     173 
     174  * There is a reserved YAML character in a key or a value, without string delimiters: 
     175 
     176    message: tell him: go way    # :, [, ], { and } are reserved in YAML 
     177    message: 'tell him: go way'  # Correct syntax 
     178 
     179  * You are modifying a commented line: 
     180 
     181    # key: value     # Will never be taken into account due to the leading # 
     182 
     183  * You set values with the same key name twice at the same level: 
     184 
     185    key1: value1 
     186    key2: value2 
     187    key1: value3     # key1 is defined twice, the value is the last one defined 
     188 
     189  * You think that the setting takes a special type, while it is always a string, until you convert it: 
     190 
     191    income: 12,345   # Until you convert it, this is still a string 
     192 
     193Overview of the Configuration Files 
     194----------------------------------- 
     195 
     196Configuration 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. 
     197 
     198### Project Configuration 
     199 
     200There are a few project configuration files by default. Here are the files that can be found in the `myproject/config/` directory: 
     201 
     202  * `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. 
     203  * `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. 
     204  * `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. 
     205  * `rs`ync_exclude.txt: This file specifies which directories must be excluded from the synchronization between servers. It is discussed in Chapter 16. 
     206  * `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. 
     207 
     208These 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. 
     209 
     210### Application Configuration 
     211 
     212The 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. 
     213 
     214#### Front Controller Configuration 
     215 
     216The 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. 
     217 
     218Listing 5-11 - The Default Production Front Controller 
     219 
     220    [php] 
     221    <?php 
     222 
     223    define('SF_ROOT_DIR',    dirname(__FILE__).'/..'); 
     224    define('SF_APP',         'myapp'); 
     225    define('SF_ENVIRONMENT', 'prod'); 
     226    define('SF_DEBUG',       true); 
     227 
     228    require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php'); 
     229 
     230    sfContext::getInstance()->getController()->dispatch(); 
     231 
     232After 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: 
     233 
     234  * `SF_ROOT_DIR`: Project root directory (normally, should remain at its default value, unless you change the file structure). 
     235  * `SF_APP`: Application name in the project. Necessary to compute file paths. 
     236  * `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. 
     237  * `SF_DEBUG`: Activation of the debug mode (see Chapter 16 for details). 
     238 
     239If 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. 
     240 
     241>**SIDEBAR** 
     242>The root directory can be anywhere 
     243> 
     244>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. 
     245> 
     246>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: 
     247> 
     248> 
     249>    symfony/    # Private area 
     250>      apps/ 
     251>      batch/ 
     252>      cache/ 
     253>      ... 
     254>    www/        # Public area 
     255>      images/ 
     256>      css/ 
     257>      js/ 
     258>      index.php 
     259> 
     260> 
     261>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: 
     262> 
     263>    define('SF_ROOT_DIR', dirname(__FILE__).'/../symfony'); 
     264 
     265Chapter 19 will give you more information about how to tweak symfony to make it work on a specific directory structure. 
     266 
     267#### Main Application Configuration 
     268 
     269The main application configuration is stored in files located in the `myproject/apps/myapp/config/` directory: 
     270 
     271  * `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. 
     272  * `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`. 
     273  * `fact`ories.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 19 provides more information. 
     274  * `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. 
     275  * `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. 
     276  * `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. 
     277  * `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. 
     278  * `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. 
     279 
     280#### Internationalization Configuration 
     281 
     282Internationalized applications can display pages in several languages. This requires specific configuration. There are two configuration places for internationalization: 
     283 
     284  * `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. 
     285  * 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. 
     286 
     287Note 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. 
     288 
     289#### Additional Application Configuration 
     290 
     291A 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: 
     292 
     293  * `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. 
     294  * `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. 
     295  * `c`ore_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. 
     296  * `config_handlers.yml`: This is where you can add or modify the handlers used to process each configuration file. Chapter 19 provides more details. 
     297  * `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. 
     298 
     299### Module Configuration 
     300 
     301By 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. 
     302 
     303As you may have guessed, module configuration files must be located in a `myproject/apps/myapp/modules/mymodule/config/` directory. These files are as follows: 
     304 
     305  * `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. 
     306  * `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. 
     307  * `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. 
     308  * `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. 
     309  * 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. 
     310 
     311Most 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. 
     312 
     313>**SIDEBAR** 
     314>**Too many files? 
     315> 
     316>You might be overwhelmed by the number of configuration files present in the application. But please keep the following in mind: 
     317> 
     318>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). 
     319> 
     320>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. 
     321 
     322Environments 
     323------------ 
     324 
     325During the course of application development, you will probably need to keep several sets of configuration in parallel. For instance, you will need to have the connection settings for your tests database available during development, and the ones for your real data available for production. To answer the need of concurrent configurations, symfony offers different environments. 
     326 
     327### What Is an Environment? 
     328 
     329An application can run in various environments. The different environments share the same PHP code (apart from the front controller), but can have completely different configurations. For each application, symfony provides three default environments: production (`prod`), test (test), and development (dev). You're also free to add as many custom environments as you wish. 
     330 
     331So basically, environments and configuration are synonyms. For instance, a test environment will log alerts and errors, while a `prod` environment will only log errors. Cache acceleration is often deactivated in the `dev` environment, but activated in the `test` and `prod` environments. The `dev` and `test` environments may need test data, stored in a database distinct from the one used in the production environment. So the database configuration will be different between the two environments. All environments can live together on the same machine, although a production server generally contains only the `prod` environment. 
     332 
     333In the `dev` environment, the logging and debugging settings are all enabled, since maintenance is more important than performance. On the contrary, the prod environment has settings optimized for performance by default, so the production configuration turns off many features. A good rule of thumb is to navigate in the development environment until you are satisfied with the feature you are working on, and then switch to the production environment to check its speed. 
     334 
     335The test environment differs from the dev and prod environment in other ways. You interact with this environment solely through the command line for the purpose of functional testing and batch scripting. Consequently, the test environment is close to the production one, but it is not accessed through a web browser. It simulates the use of cookies and other HTTP specific components. 
     336 
     337To change the environment in which you're browsing your application, just change the front controller. Until now, you have seen only the development environment, since the URLs used in the example called the development front controller: 
     338 
     339    http://localhost/myapp_dev.php/mymodule/index 
     340 
     341However, if you want to see how the application reacts in production, call the production front controller instead: 
     342 
     343    http://localhost/index.php/mymodule/index 
     344 
     345If your web server has mod_rewrite enabled, you can even use the custom symfony rewriting rules, written in `web/.htaccess`. They define the production front controller as the default execution script and allow for URLs like this: 
     346 
     347    http://localhost/mymodule/index 
     348 
     349>**SIDEBAR** 
     350>Environments and servers 
     351> 
     352>Don't mix up the notions of environment and server. In symfony, different environments are different configurations, and correspond to a front controller (the script that executes the request). Different servers correspond to different domain names in the URL. 
     353> 
     354> 
     355>    http://localhost/myapp_dev.php/mymodule/index 
     356>           _________ _____________ 
     357>            server    environment 
     358> 
     359> 
     360>Usually, developers work on applications in a development server, disconnected from the Internet and where all the server and PHP configuration can be changed at will. When the time comes for releasing the application to production, the application files are transferred to the production server and made accessible to the end users. 
     361> 
     362>This means that many environments are available on each server. For instance, you can run in the production environment even on your development server. However, most of the time, only the production environment should be accessible in the production server, to avoid public visibility of server configuration and security risks. 
     363> 
     364>To add a new environment, you don't need to create a directory or to use the symfony CLI. Simply create a new front controller and change the environment name definition in it. This environment inherits all the default configuration plus the settings that are common to all environments. The next chapter will show you how to do this. 
     365 
     366### Configuration Cascade 
     367 
     368The same setting can be defined more than once, in different places. For instance, you may want to set the mime-type of your pages to `text/html` for all of the application, except for the pages of an `rss` module, which will need a `text/xml` mime-type. Symfony gives you the ability to write the first setting in `myapp/config/view.yml` and the second in `myapp/modules/rss/config/view.yml`. The configuration system knows that a setting defined at the module level must override a setting defined at the application level. 
     369 
     370In fact, there are several configuration levels in symfony: 
     371 
     372  * Granularity levels: 
     373    * The default configuration located in the framework 
     374    * The global configuration for the whole project (in `myproject/config/`) 
     375    * The local configuration for an application of the project (in `myproject/apps/myapp/config/`) 
     376    * The local configuration restricted to a module (in `myproject/apps/myapp/modules/mymodule/config/`) 
     377  * Environment levels: 
     378    * Specific to one environment 
     379    * For all environments 
     380 
     381Of all the properties that can be customized, many are environment-dependent. Consequently, many YAML configuration files are divided by environment, plus a tail section for all environments. The result is that typical symfony configuration looks like Listing 5-12. 
     382 
     383Listing 5-12 - The Structure of Symfony Configuration Files 
     384 
     385    # Production environment settings 
     386    prod: 
     387      ... 
     388 
     389    # Development environment settings 
     390    dev: 
     391      ... 
     392 
     393    # Test environment settings 
     394    test: 
     395      ... 
     396 
     397    # Custom environment settings 
     398    myenv: 
     399      ... 
     400 
     401    # Settings for all environments 
     402    all: 
     403      ... 
     404 
     405In addition, the framework itself defines default values in files that are not located in the project tree structure, but in the $sf_symfony_data_dir/config/ directory of your symfony installation. The default configuration is set in these files as shown in Listing 5-13. These settings are inherited by all applications. 
     406 
     407Listing 5-13 - The Default Configuration, in `$sf_symfony_data_dir/config/settings.yml` 
     408 
     409     # Default settings: 
     410     default: 
     411       default_module:         default 
     412       default_action:         index 
     413       ... 
     414 
     415These default definitions are repeated in the project, application, and module configuration files as comments, as shown in Listing 5-14, so that you know that some parameters are defined by default and that they can be modified. 
     416 
     417Listing 5-14 - The Default Configuration, Repeated for Information, in `myapp/config/settings.yml` 
     418 
     419    #all: 
     420     #  default_module:         default 
     421     #  default_action:         index 
     422     ... 
     423 
     424This means that a property can be defined several times, and the actual value results from a definition cascade. A parameter definition in a named environment has precedence over the same parameter definition for all environments, which has precedence over a definition in the default configuration. A parameter definition at the module level has precedence over the same parameter definition at the application level, which has precedence over a definition at the project level. This can be wrapped up in the following priority list: 
     425 
     426  1. Module 
     427  2. Application 
     428  3. Project 
     429  4. Specific environment 
     430  5. All environments 
     431  6. Default 
     432 
     433The Configuration Cache 
     434----------------------- 
     435 
     436Parsing YAML and dealing with the configuration cascade at runtime represent a significant overhead for each request. Symfony has a built-in configuration cache mechanism designed to speed up requests. 
     437 
     438The configuration files, whatever their format, are processed by some special classes, called handlers, that transform them into fast-processing PHP code. In the development environment, the handlers check the configuration for changes at each request, to promote interactivity. They parse the recently modified files so that you can see a change in a YAML file immediately. But in the production environment, the processing occurs once during the first request, and then the processed PHP code is stored in the cache for subsequent requests. The performance is guaranteed, since every request in production will just execute some well-optimized PHP code. 
     439 
     440For instance, if the `app.yml` file contains this: 
     441 
     442    all:                   # Setting for all environments 
     443      mail: 
     444        webmaster:         webmaster@example.com 
     445 
     446then the file `config_app.yml.php`, located in the `cache/` folder of your project, will contain this: 
     447 
     448    [php] 
     449    <?php 
     450 
     451    sfConfig::add(array( 
     452      'app_mail_webmaster' => 'webmaster@example.com', 
     453    )); 
     454 
     455As a consequence, most of the time, the YAML files aren't even parsed by the framework, which relies on the configuration cache instead. However, in the development environment, symfony will systematically compare the dates of modification of the YAML files and the cached files, and reprocess only the ones that have changed since the previous request. 
     456 
     457This presents a major advantage over many PHP frameworks, where configuration files are compiled at every request, even in production. Unlike Java, PHP doesn't share an execution context between requests. For other PHP frameworks, keeping the flexibility of XML configuration files requires a major performance hit to process all the configuration at every request. This is not the case in symfony. Thanks to the cache system, the overhead caused by configuration is very low. 
     458 
     459There is an important consequence of this mechanism. If you change the configuration in the production environment, you need to force the reparsing of all the configuration files for your modification to be taken into account. For that, you just need to clear the cache, either by deleting the content of the cache/ directory or, more easily, by calling the clear-cache symfony task: 
     460 
     461    > symfony clear-cache 
     462 
     463Accessing the Configuration from Code 
     464------------------------------------- 
     465 
     466All 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. 
     467 
     468### The sfConfig Class 
     469 
     470You 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: 
     471 
     472    [php] 
     473    // Retrieve a setting 
     474    parameter = sfConfig::get('param_name', $default_value); 
     475 
     476Note that you can also define, or override, a setting from within PHP code: 
     477 
     478    [php] 
     479    // Define a setting 
     480    sfConfig::set('param_name', $value); 
     481 
     482The parameter name is the concatenation of several elements, separated by underscores, in this order: 
     483 
     484  * 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`) 
     485  * The parent keys (if defined), in lowercase 
     486  * The name of the key, in lowercase 
     487 
     488The environment is not included, since your PHP code will have access only to the values defined for the environment in which it's executed. 
     489 
     490For 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. 
     491 
     492Listing 5-15 - Sample `app.yml` Configuration 
     493 
     494    all: 
     495      version:        1.5 
     496      .general: 
     497        tax:          19.6 
     498      default_user: 
     499        name:         John Doe 
     500      mail: 
     501        webmaster:    webmaster@example.com 
     502        contact:      contact@example.com 
     503    dev: 
     504      mail: 
     505        webmaster:    dummy@example.com 
     506        contact:      dummy@example.com 
     507 
     508Listing 5-16 - Accessing Configuration Settings in PHP in the `dev` Environment 
     509 
     510    [php] 
     511    echo sfConfig::get('app_version'); 
     512     => '1.5' 
     513    echo sfConfig::get('app_tax');   // Remember that category headers are ignored 
     514     => '19.6' 
     515    echo sfConfig::get('app_default_user_name); 
     516     => 'John Doe' 
     517    echo sfConfig::get('app_mail_webmaster'); 
     518     => 'dummy@example.com' 
     519    echo sfConfig::get('app_mail_contact'); 
     520     => 'dummy@example.com' 
     521 
     522So symfony configuration settings have all the advantages of PHP constants, but without the disadvantages, since the value can be changed. 
     523 
     524On 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. 
     525 
     526Listing 5-17 - Extract of `settings.yml` 
     527 
     528    all: 
     529      .settings: 
     530        available:              on 
     531        path_info_array:        SERVER 
     532        path_info_key:          PATH_INFO 
     533        url_format:             PATH 
     534 
     535Listing 5-18 - What Symfony Does When Parsing `settings.yml` 
     536 
     537    [php] 
     538    sfConfig::add(array( 
     539      'sf_available' => true, 
     540      'sf_path_info_array' => 'SERVER', 
     541      'sf_path_info_key' => 'PATH_INFO', 
     542      'sf_url_format' => 'PATH', 
     543    )); 
     544 
     545Refer to Chapter 19 for the meanings of the settings found in the `settings.yml` file. 
     546 
     547### Custom Application Settings and app.yml 
     548 
     549Most 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. 
     550 
     551Listing 5-19 - Sample `app.yml` to Define Credit Card Operators Accepted for a Given Site 
     552 
     553    all: 
     554      creditcards: 
     555        fake:             off 
     556        visa:             on 
     557        americanexpress:  on 
     558 
     559    dev: 
     560      creditcards: 
     561        fake:             on 
     562 
     563To know if the `fake` credit cards are accepted in the current environment, get the value of: 
     564 
     565    [php] 
     566    sfConfig::get('app_creditcards_fake'); 
     567 
     568>**TIP** 
     569>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. 
     570 
     571When 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. 
     572 
     573Tips for Getting More from Configuration Files 
     574---------------------------------------------- 
     575 
     576There are a few last tricks to learn before writing your own YAML files. They will allow you to avoid configuration duplication and to deal with your own YAML formats. 
     577 
     578### Using Constants in YAML Configuration Files 
     579 
     580Some configuration settings rely on the value of other settings. To avoid setting the same value twice, symfony supports constants in YAML files. On encountering a setting name (one that can be accessed by sfConfig::get()) in capital letters enclosed in % signs, the configuration handlers replace them with their current value. See Listing 5-20 for an example. 
     581 
     582Listing 5-20 - Using Constants in YAML Files, Example from `autoload.yml` 
     583 
     584    autoload: 
     585      symfony: 
     586        name:           symfony 
     587        path:           %SF_SYMFONY_LIB_DIR% 
     588        recursive:      on 
     589        exclude:        [vendor] 
     590 
     591The path parameter will take the value returned by sfConfig::get('sf_symfony_lib_dir'). If you want one configuration file to rely on another, you need to make sure that the file you rely on is already parsed (look in the symfony source to find out the order in which the configuration files are parsed). `app.yml` is one of the last files parsed, so you may rely on others in it. 
     592 
     593### Using Scriptable Configuration 
     594 
     595It may happen that your configuration relies on external parameters (such as a database or another configuration file). To deal with these particular cases, the symfony configuration files are parsed as PHP files before being passed to the YAML parser. It means that you can put PHP code in YAML files, as in Listing 5-21. 
     596 
     597Listing 5-21 - YAML Files Can Contain PHP 
     598 
     599    all: 
     600      translation: 
     601        format:  <?php echo sfConfig::get('sf_i18n') == true ? 'xliff' : 'none' ?> 
     602 
     603But be aware that the configuration is parsed very early in the life of a request, so you will not have any symfony built-in methods or functions to help you. 
     604 
     605>**CAUTION** 
     606>In the production environment, the configuration is cached, so the configuration files are parsed (and executed) only once after the cache is cleared. 
     607 
     608### Browsing Your Own YAML File 
     609 
     610Whenever you want to read a YAML file directly, you can use the `sfYaml` class. It is a YAML parser that can turn a YAML file into a PHP associative array. Listing 5-22 presents a sample YAML file, and Listing 5-23 shows you how to parse it. 
     611 
     612Listing 5-22 - Sample `test.yml` File 
     613 
     614    house: 
     615      family: 
     616        name:     Doe 
     617        parents:  [John, Jane] 
     618        children: [Paul, Mark, Simone] 
     619      address: 
     620        number:   34 
     621        street:   Main Street 
     622        city:     Nowheretown 
     623        zipcode:  12345 
     624 
     625Listing 5-23 - Using the `sfYaml` Class to Turn a YAML File into an Associative Array 
     626 
     627    [php] 
     628    $test = sfYaml::load('/path/to/test.yml'); 
     629    print_r($test); 
     630 
     631    Array( 
     632      [house] => Array( 
     633        [family] => Array( 
     634          [name] => Doe 
     635          [parents] => Array( 
     636            [0] => John 
     637            [1] => Jane 
     638          ) 
     639          [children] => Array( 
     640            [0] => Paul 
     641            [1] => Mark 
     642            [2] => Simone 
     643          ) 
     644        ) 
     645        [address] => Array( 
     646          [number] => 34 
     647          [street] => Main Street 
     648          [city] => Nowheretown 
     649          [zipcode] => 12345 
     650        ) 
     651      ) 
     652    ) 
     653 
     654Summary 
     655------- 
     656 
     657The symfony configuration system uses the YAML language to be simple and readable. The ability to deal with multiple environments and to set parameters through a definition cascade offers versatility to the developer. Some of the configuration can be accessed from within the code via the `sfConfig` object, especially the application settings stored in the `app.yml` file. 
     658 
     659Yes, symfony does have a lot of configuration files, but this approach makes it more adaptable. Remember that you don't need to bother with them unless your application requires a high level of customization. 
     660 
     661}}} 
     662 
     663---- 
     664[wiki:Documentation/ja_JP/ 目次]