| [ Index ] |
|
Code source de Symfony 1.0.0 |
1 Chapter 19 - Mastering Symfony's Configuration Files 2 ==================================================== 3 4 Now that you know symfony very well, you are already able to dig into its code to understand its core design and discover new hidden abilities. But before extending the symfony classes to match your own requirements, you should take a closer look at some of the configuration files. Many features are already built into symfony and can be activated by just changing configuration settings. This means that you can tweak the symfony core behavior without overriding its classes. This chapter takes you deep into the configuration files and their powerful capabilities. 5 6 Symfony Settings 7 ---------------- 8 9 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. 10 11 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')`. 12 13 ### Default Modules and Actions 14 15 When a routing rule doesn't define the `module` or the `action` parameter, values from the `settings.yml` file are used instead: 16 17 * `default_module`: Default `module` request parameter. Defaults to the `default` module. 18 * `default_action`: Default `action` request parameter. Defaults to the `index` action. 19 20 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: 21 22 * `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`. 23 * `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`. 24 * `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`. 25 * `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`. 26 * `unavailable_module` and `unavailable_action`: Action called when a user requests a page from a disabled application. The default value is `default/unavailable`. To disable an application, set the `available` parameter to `off` in `settings.yml`. 27 28 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. 29 30 Figure 19-1 - Default 404 error page 31 32  33 34 You can override the default pages in two ways: 35 36 * 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 `unavailable`) and all the related templates (`indexSuccess.php`, `error404Success.php`, `loginSuccess.php`, `secureSuccess.php`, `disabledSuccess.php`, and `unavailableSuccess.php`). 37 * You can change the default module and action settings of the `settings.yml` file to use pages of your application. 38 39 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: 40 41 * `error500.php`: Page called when an internal server error occurs in the production environment. In other environments (where `SF_DEBUG` is set to `true`), when an error occurs, symfony displays the full execution stack and an explicit error message (see Chapter 16 for details). 42 * `unavailable.php`: Page called when a user requests a page while the cache is being cleared (that is, between a call to the `symfony 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. The `unavailable.php` page is also used when an application is disabled via the `symfony disable` command (see Chapter 16 for details). 43 44 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. 45 46 >**NOTE** 47 >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. 48 49 ### Optional Feature Activation 50 51 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. 52 53 Table 19-1 - Optional Features Set Through `settings.yml` 54 55 Parameter | Description | Default Value 56 ----------------------- | ----------- | ------------- 57 `use_database` | Enables the database manager. Set it to `off` if you don't use a database. | `on` 58 `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` 59 `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` 60 `i18n` | Enables interface translation (see Chapter 13). Set it to `on` for multilingual applications. | `off` 61 `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` 62 `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` 63 `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 64 `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 ony if it is on. | `on` in development, `off` in production 65 `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` 66 `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` 67 `compressed` | Enables PHP response compression. Set it to `on` to compress the outgoing HTML via the PHP compression handler. | `off` 68 `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` 69 70 ### Feature Configuration 71 72 Symfony uses some parameters of `settings.yml` to alter the behavior of built-in features such as form validation, cache, and third-party modules. 73 74 #### Output Escaping Settings 75 76 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: 77 78 * The `escaping_strategy` setting can take the value `bc`, `both`, `on`, or `off`. 79 * The escaping_method setting can be set to `ESC_RAW`, `ESC_ENTITIES`, `ESC_JS`, or `ESC_JS_NO_ENTITIES`. 80 81 #### Routing Settings 82 83 Two routing settings (see Chapter 9) are stored in `settings.yml`: 84 85 * 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. 86 * The `no_script_name` parameter 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. 87 88 #### Form Validation Settings 89 90 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"`. 91 92 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. 93 94 #### Cache Settings 95 96 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). 97 98 #### Logging Settings 99 100 Two logging settings (see Chapter 16) are stored in `settings.yml`: 101 102 * `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 are `E_PARSE`, `E_COMPILE_ERROR`, `E_ERROR`, `E_CORE_ERROR`, and `E_USER_ERROR`) and to 4095 for the development environment (`E_ALL` and `E_STRICT`). 103 * The `web_debug` setting activates the web debug toolbar. Set it to `on` only in the development and test environments. 104 105 #### Paths to Assets 106 107 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: 108 109 * Rich text editor JavaScript files stored in `rich_text_js_dir` (by default, `js/tiny_mce`) 110 * Prototype libraries stored in `prototype_web_dir` (by default, `/sf/prototype`) 111 * Files needed by the administration generator stored in `admin_web_dir` 112 * Files needed by the web debug toolbar stored in `web_debug_web_dir` 113 * Files needed by the javascript calendar stored in `calendar_web_dir` 114 115 #### Default Helpers 116 117 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. 118 119 #### Activated Modules 120 121 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. 122 123 #### Character Set 124 125 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`. 126 127 #### Miscellaneous Configuration 128 129 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. 130 131 Listing 19-1 - Miscellaneous Configuration Settings, in `myapp/config/settings.yml` 132 133 # Remove comments in core framework classes as defined in the core_compile.yml 134 strip_comments: on 135 # Functions called when a class is requested and not already loaded 136 # Expects an array of callables. Used by the framework bridges. 137 autoloading_functions: ~ 138 # Session timeout, in seconds 139 timeout: 1800 140 # Maximum number of forwards followed by the action before raising an exception 141 max_forwards: 5 142 # Global constants 143 path_info_array: SERVER 144 path_info_key: PATH_INFO 145 url_format: PATH 146 147 >**SIDEBAR** 148 >Adding Your application settings 149 > 150 >The `settings.yml` file defines symfony settings for an application. As discussed in Chapter 5, when you want to add new parameters, the best place to do so is in the `myapp/config/app.yml` file. This file is also environment-dependent, and the settings it defines are available through the sfConfig class with the `app_` prefix. 151 > 152 > 153 > all: 154 > creditcards: 155 > fake: off # app_creditcards_fake 156 > visa: on # app_creditcards_visa 157 > americanexpress: on # app_creditcards_americanexpress 158 > 159 > 160 >You can also write an `app.yml` file in the project configuration directory, and this provides a way to define custom project settings. The configuration cascade also applies to this file, so the settings defined in the application `app.yml` file override the ones defined at the project level. 161 162 Extending the Autoloading Feature 163 --------------------------------- 164 165 The autoloading feature, briefly explained in Chapter 2, exempts you from requiring classes in your code if they are located in specific directories. This means that you can just let the framework do the job for you, allowing it to load only the necessary classes at the appropriate time, and only when needed. 166 167 The `autoload.yml` file lists the paths in which autoloaded classes are stored. The first time this configuration file is processed, symfony parses all the directories referenced in the file. Each time a file ending with `.php` is found in one of these directories, the file path and the class names found in this file are added to an internal list of autoloading classes. This list is saved in the cache, in a file called `config/config_autoload.yml.php`. Then, at runtime, when a class is used, symfony looks in this list for the class path and includes the `.php` file automatically. 168 169 Autoloading works for all `.php` files containing classes and/or interfaces. 170 171 By default, classes stored in the following directories in your projects benefit from the autoloading automatically: 172 173 * `myproject/lib/` 174 * `myproject/lib/model` 175 * `myproject/apps/myapp/lib/` 176 * `myproject/apps/myapp/modules/mymodule/lib` 177 178 There is no `autoload.yml` file in the default application configuration directory. If you want to modify the framework settings--for instance, to autoload classes stored somewhere else in your file structure--create an empty autoload.yml file and override the settings of `$sf_symfony_data_dir/config/autoload.yml` or add your own. 179 180 The autoload.yml file must start with an autoload: key and list the locations where symfony should look for classes. Each location requires a label; this gives you the ability to override symfony's entries. For each location, provide a `name` (it will appear as a comment in `config_autoload.yml.php`) and an absolute `path`. Then define if the search must be `recursive`, which directs symfony to look in all the subdirectories for `.php` files, and `exclude` the subdirectories you want. Listing 19-2 shows the locations used by default and the file syntax. 181 182 Listing 19-2 - Default Autoloading Configuration, in `$sf_symfony_data_dir/config/autoload.yml` 183 184 autoload: 185 186 # symfony core 187 symfony: 188 name: symfony 189 path: %SF_SYMFONY_LIB_DIR% 190 recursive: on 191 exclude: [vendor] 192 193 propel: 194 name: propel 195 path: %SF_SYMFONY_LIB_DIR%/vendor/propel 196 recursive: on 197 198 creole: 199 name: creole 200 path: %SF_SYMFONY_LIB_DIR%/vendor/creole 201 recursive: on 202 203 propel_addon: 204 name: propel addon 205 files: 206 Propel: %SF_SYMFONY_LIB_DIR%/addon/propel/sfPropelAutoload.php 207 208 # plugins 209 plugins_lib: 210 name: plugins lib 211 path: %SF_PLUGINS_DIR%/*/lib 212 recursive: on 213 214 plugins_module_lib: 215 name: plugins module lib 216 path: %SF_PLUGINS_DIR%/*/modules/*/lib 217 prefix: 2 218 recursive: on 219 220 # project 221 project: 222 name: project 223 path: %SF_LIB_DIR% 224 recursive: on 225 exclude: [model, symfony] 226 227 project_model: 228 name: project model 229 path: %SF_MODEL_LIB_DIR% 230 recursive: on 231 232 # application 233 application: 234 name: application 235 path: %SF_APP_LIB_DIR% 236 recursive: on 237 238 modules: 239 name: module 240 path: %SF_APP_DIR%/modules/*/lib 241 prefix: 1 242 recursive: on 243 244 A rule path can contain wildcards and use the file path parameters from the `constants.php` file (see the next section). If you use these parameters in the configuration file, they must appear in uppercase and begin and end with `%`. 245 246 Editing your own `autoload.yml` will add new locations to symfony's autoloading, but you may want to extend this mechanism and add your own autoloading handler to symfony's handler. This is possible through the `autoloading_functions` parameter in the `settings.yml` file. It expects an array of callables as a value, as follows: 247 248 .settings: 249 autoloading_functions: 250 - [myToolkit, autoload] 251 252 When symfony encounters a new class, it will first try its own autoloading system (and use the locations defined in `autoload.yml`). If it doesn't find a class definition, it will then try the other autoloading functions from `settings.yml`, until the class is found. So you can add as many autoloading mechanisms as you want--for instance, to provide a bridge to other framework components (see Chapter 17). 253 254 Custom File Structure 255 --------------------- 256 257 Each time the framework uses a path to look for something (from core classes to templates, plug-ins, configurations, and so on), it uses a path variable instead of an actual path. By changing these variables, you can completely alter the directory structure of a symfony project, and adapt to the file organization requirements of any client. 258 259 >**CAUTION** 260 >Customizing the directory structure of a symfony project is possible but not necessarily a good idea. One of the strengths of a framework like symfony is that any web developer can look at a project built with it and feel at home, because of the respect for conventions. Make sure you consider this issue before deciding to use your own directory structure. 261 262 ### The Basic File Structure 263 264 The path variables are defined in the `$sf_symfony_data_dir/config/constants.php` file, included when the application bootstraps. These variables are stored in the `sfConfig` object, and so they are easy to override. Listing 19-3 shows a listing of the path variables and the directory they reference. 265 266 Listing 19-3 - Default File Structure Variables, from `$sf_symfony_data_dir/config/constants.php` 267 268 sf_root_dir # myproject/ 269 # apps/ 270 sf_app_dir # myapp/ 271 sf_app_config_dir # config/ 272 sf_app_i18n_dir # i18n/ 273 sf_app_lib_dir # lib/ 274 sf_app_module_dir # modules/ 275 sf_app_template_dir # templates/ 276 sf_bin_dir # batch/ 277 # cache/ 278 sf_base_cache_dir # myapp/ 279 sf_cache_dir # prod/ 280 sf_template_cache_dir # templates/ 281 sf_i18n_cache_dir # i18n/ 282 sf_config_cache_dir # config/ 283 sf_test_cache_dir # test/ 284 sf_module_cache_dir # modules/ 285 sf_config_dir # config/ 286 sf_data_dir # data/ 287 sf_doc_dir # doc/ 288 sf_lib_dir # lib/ 289 sf_model_lib_dir # model/ 290 sf_log_dir # log/ 291 sf_test_dir # test/ 292 sf_plugins_dir # plugins/ 293 sf_web_dir # web/ 294 sf_upload_dir # uploads/ 295 296 Every path to a key directory is determined by a parameter ending with `_dir`. Always use the path variables instead of real (relative or absolute) file paths, so that you will be able to change them later, if necessary. For instance, when you want to move a file to the `uploads/` directory in an application, you should use `sfConfig::get('sf_upload_dir')` for the path instead of `SF_ROOT_DIR.'/web/uploads/'`. 297 298 The module directory structure is defined at runtime, when the routing system determines the module name (`$module_name`). It is automatically built according to the path names defined in the `constants.php` file, as shown in Listing 19-4. 299 300 Listing 19-4 - Default Module File Structure Variables 301 302 sf_app_module_dir # modules/ 303 module_name # mymodule/ 304 sf_app_module_action_dir_name # actions/ 305 sf_app_module_template_dir_name # templates/ 306 sf_app_module_lib_dir_name # lib/ 307 sf_app_module_view_dir_name # views/ 308 sf_app_module_validate_dir_name # validate/ 309 sf_app_module_config_dir_name # config/ 310 sf_app_module_i18n_dir_name # i18n/ 311 312 So, for instance, the path to the `validate/` directory of the current module is built dynamically at runtime: 313 314 [php] 315 sfConfig::get('sf_app_module_dir').'/'.$module_name.'/'.sfConfig::get('sf_app_module_validate_dir_name') 316 317 ### Customizing the File Structure 318 319 You will probably need to modify the default project file structure if you develop an application for a client who already has a defined directory structure and who is not willing to change it to comply with the symfony logic. By overriding the `sf_XXX_dir` and `sf_XXX_dir_name` variables with `sfConfig`, you can make symfony work for a totally different directory structure than the default structure. The best place to do this is in the application `config.php` file. 320 321 >**CAUTION** 322 >Use the application `config.php` and not the project one to override the `sf_XXX_dir` and `sf_XXX_dir_name` variables with `sfConfig`. The project `config/config.php` file is loaded very early in the life of a request, at a time when the `sfConfig` class doesn't exist yet, and when the `constants.php` file is not yet loaded. 323 324 For instance, if you want all applications to share a common directory for the template layouts, add this line to the `myapp/config/config.php` file to override the `sf_app_template_dir` settings: 325 326 [php] 327 sfConfig::set('sf_app_template_dir', sfConfig::get('sf_root_dir').DIRECTORY_SEPARATOR.'templates'); 328 329 Note that the application config.php file is not empty, so if you need to include file structure definitions there, do it at the end of the file. 330 331 ### Modifying the Project Web Root 332 333 All the paths built in `constants.php` rely on the project root directory, which is a constant defined in the front controller (`SF_ROOT_DIR`). Usually, the root directory is one level above the `we`b/ directory, but you can use a different structure. Suppose that your main directory structure is made of two directories, one public and one private, as shown in Listing 19-5. This typically happens when hosting a project on a shared host. 334 335 Listing 19-5 - Example of Custom Directory Structure for a Shared Host 336 337 symfony/ # Private area 338 apps/ 339 batch/ 340 cache/ 341 ... 342 www/ # Public area 343 images/ 344 css/ 345 js/ 346 index.php 347 348 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: 349 350 [php] 351 define('SF_ROOT_DIR', dirname(__FILE__).'/../symfony'); 352 353 In addition, since the public area is `www/` instead of the usual `web/`, you must override two file paths in the application `config.php` file, as follows: 354 355 [php] 356 sfConfig::add(array( 357 'sf_web_dir' => SF_ROOT_DIR.DIRECTORY_SEPARATOR.'www', 358 'sf_upload_dir' => SF_ROOT_DIR.DIRECTORY_SEPARATOR.'www'.DIRECTORY_SEPARATOR.sfConfig::get('sf_upload_dir_name'), 359 )); 360 361 ### Linking to Symfony Libraries 362 363 The paths to the framework files are defined in the project `config.php` file, as you can see in Listing 19-6. 364 365 Listing 19-6 - The Paths to the Framework Files, in `myproject/config/config.php` 366 367 [php] 368 <?php 369 370 // symfony directories 371 $sf_symfony_lib_dir = '/path/to/symfony/lib'; 372 $sf_symfony_data_dir = '/path/to/symfony/data'; 373 374 These paths are initialized when you call a `symfony init-project` from the command line, and refer to the symfony installation used to build the project. They are used both by the command line and by the MVC architecture. 375 376 This means that you can switch to another installation of symfony by changing the paths to the framework files. 377 378 These paths should be absolute, but by using `dirname(__FILE__)`, you can refer to files inside the project structure and preserve independence of the chosen directory for the project installation. For instance, many projects choose to have the symfony `lib/` directory appear as a symbolic link in the project `lib/symfony/` directory, and do the same for the symfony `data/` directory, as follows: 379 380 myproject/ 381 lib/ 382 symfony/ => /path/to/symfony/lib 383 data/ 384 symfony/ => /path/to/symfony/data 385 386 In this case, the project config.php file just needs to define the symfony directories as follows: 387 388 [php] 389 $sf_symfony_lib_dir = dirname(__FILE__).'/../lib/symfony'; 390 $sf_symfony_data_dir = dirname(__FILE__).'/../data/symfony'; 391 392 The same principle also applies if you choose to include the symfony files as a `svn:externals` in the project `lib/vendor/` directory: 393 394 myproject/ 395 lib/ 396 vendor/ 397 svn:externals symfony http://svn.symfony-project.com/trunk/ 398 399 In this case, the `config.php` file should look like this: 400 401 [php] 402 $sf_symfony_lib_dir = dirname(__FILE__).'/../lib/vendor/symfony/lib'; 403 $sf_symfony_data_dir = dirname(__FILE__).'/../lib/vendor/symfony/data'; 404 405 >**TIP** 406 >Sometimes, the different servers running an application don't have the same path to the symfony libraries. One way to enable that is to exclude the project `config.php` file from the synchronization (by adding it to `rsync_exclude.txt`). Another method is to keep the same paths in the development and production versions of `config.php`, but to have these paths point to symbolic links that can vary according to the server. 407 408 Understanding Configuration Handlers 409 ------------------------------------ 410 411 Each configuration file has a handler. The job of configuration handlers is to manage the configuration cascade, and to do the translation between the configuration files and the optimized PHP code executable at runtime. 412 413 ### Default Configuration Handlers 414 415 The default handler configuration is stored in `$sf_symfony_data_dir/config/config_handlers.yml`. This file links the handlers to the configuration files according to a file path. Listing 19-7 shows an extract of this file. 416 417 Listing 19-7 - Extract of `$sf_symfony_data_dir/config/config_handlers.yml` 418 419 config/settings.yml: 420 class: sfDefineEnvironmentConfigHandler 421 param: 422 prefix: sf_ 423 424 config/app.yml: 425 class: sfDefineEnvironmentConfigHandler 426 param: 427 prefix: app_ 428 429 config/filters.yml: 430 class: sfFilterConfigHandler 431 432 modules/*/config/module.yml: 433 class: sfDefineEnvironmentConfigHandler 434 param: 435 prefix: mod_ 436 module: yes 437 438 For each configuration file (`config_handlers.yml` identifies each file by a file path with wildcards), the handler class is specified under the `class` key. 439 440 The settings of configuration files handled by `sfDefineEnvironmentConfigHandler` can be made available directly in the code via the `sfConfig` class, and the param key contains a prefix value. 441 442 You can add or modify the handlers used to process each configuration file--for instance, to use INI or XML files instead of YAML files. 443 444 >**NOTE** 445 >The configuration handler for the `config_handlers.yml` file is `sfRootConfigHandler` and, obviously, it cannot be changed. 446 447 If you ever need to modify the way the configuration is parsed, create an empty `config_handlers.yml` file in your application's `config/` folder and override the `class` lines with the classes you wrote. 448 449 ### Adding Your Own Handler 450 451 Using a handler to deal with a configuration file provides two important benefits: 452 453 * The configuration file is transformed into executable PHP code, and this code is stored in the cache. This means that the configuration is parsed only once in production, and the performance is optimal. 454 * The configuration file can be defined at different levels (project and application) and the final parameter values will result from a cascade. So you can define parameters at a project level and override them on a per-application basis. 455 456 If you feel like writing your own configuration handler, follow the example of the structure used by the framework in the `$sf_symfony_lib_dir/config/` directory. 457 458 Let's suppose that your application contains a `myMapAPI` class, which provides an interface to a third-party web service delivering maps. This class needs to be initialized with a URL and a user name, as shown in Listing 19-8. 459 460 Listing 19-8 - Example of Initialization of the `myMapAPI` Class 461 462 [php] 463 $mapApi = new myMapAPI(); 464 $mapApi->setUrl($url); 465 $mapApi->setUser($user); 466 467 You may want to store these two parameters in a custom configuration file called `map.yml`, located in the application config/ directory. This configuration file might contain the following: 468 469 api: 470 url: map.api.example.com 471 user: foobar 472 473 In order to transform these settings into code equivalent to Listing 19-8, you must build a configuration handler. Each configuration handler must extend `sfConfigHandler` and provide an `execute()` method, which expects an array of file paths to configuration files as a parameter, and must return data to be written in a cache file. Handlers for YAML files should extend the `sfYamlConfigHandler` class, which provides additional facilities for YAML parsing. For the `map.yml` file, a typical configuration handler could be written as shown in Listing 19-9. 474 475 Listing 19-9 - A Custom Configuration Handler, in `myapp/lib/myMapConfigHandler.class.php` 476 477 [php] 478 <?php 479 480 class myMapConfigHandler extends sfYamlConfigHandler 481 { 482 public function execute($configFiles) 483 { 484 $this->initialize(); 485 486 // Parse the yaml 487 $config = $this->parseYamls($configFiles); 488 489 $data = "<?php\n"; 490 $data. = "\$mapApi = new myMapAPI();\n"; 491 492 if (isset($config['api']['url']) 493 { 494 $data. = sprintf("\$mapApi->setUrl('%s');\n", $config['api']['url']); 495 } 496 497 if (isset($config['api']['user']) 498 { 499 $data. = sprintf("\$mapApi->setUser('%s');\n", $config['api']['user']); 500 } 501 502 return $data; 503 } 504 } 505 506 The `$configFiles` array that symfony passes to the `execute()` method will contain a path to all the `map.yml` files found in the `config/` folders. The `parseYamls()` method will handle the configuration cascade. 507 508 In order to associate this new handler with the `map.yml` file, you must create a `config_handlers.yml` configuration file with the following content: 509 510 config/map.yml: 511 class: myMapConfigHandler 512 513 >**NOTE** 514 >The `class` must either be autoloaded (that's the case here) or defined in the file whose path is written in a `file` parameter under the `param` key. 515 516 When you need the code based on the `map.yml` file and generated by the `myMapConfigHandler` handler in your application, call the following line: 517 518 [php] 519 include(sfConfigCache::getInstance()->checkConfig(sfConfig::get('sf_app_config_dir_name').'/map.yml')); 520 521 When calling the `checkConfig()` method, symfony looks for existing `map.yml` files in the configuration directories and processes them with the handler specified in the `config_handlers.yml` file, if a `map.yml.php` does not already exist in the cache or if the `map.yml` file is more recent than the cache. 522 523 >**TIP** 524 >If you want to handle environments in a YAML configuration file, the handler can extend the `sfDefineEnvironmentConfigHandler` class instead of `sfYamlConfigHandler`. After calling the `parseYaml()` method to retrieve configuration, you should call the `mergeEnvironment()` method. You can do it all in one line by calling `$config = $this->mergeEnvironment($this->parseYamls ($configFiles));`. 525 526 - 527 528 >**SIDEBAR** 529 >Using Existing configuration handlers 530 > 531 >If you just need to allow users to retrieve values from the code via `sfConfig`, you can use the `sfDefineEnvironmentConfigHandler` configuration handler class. For instance, to have the `url` and `user` parameters available as `sfConfig::get('map_url')` and `sfConfig::get('map_user')`, define your handler as follows: 532 > 533 > config/map.yml: 534 > class: sfDefineEnvironmentConfigHandler 535 > param: 536 > prefix: map_ 537 > 538 >Be careful not to choose a prefix already used by another handler. Existing prefixes are sf_, app_, and mod_. 539 540 Controlling PHP Settings 541 ------------------------ 542 543 In order to have a PHP environment compatible with the rules and best practices of agile development, symfony checks and overrides a few settings of the `php.ini` configuration. This is the purpose of the `php.yml` file. Listing 19-10 shows the default `php.yml` file. 544 545 Listing 19-10 - Default PHP Settings for Symfony, in `$sf_symfony_data_dir/config/php.yml` 546 547 set: 548 magic_quotes_runtime: off 549 log_errors: on 550 arg_separator.output: | 551 & 552 553 check: 554 zend.ze1_compatibility_mode: off 555 556 warn: 557 magic_quotes_gpc: off 558 register_globals: off 559 session.auto_start: off 560 561 The main purpose of this file is to check that the PHP configuration is compatible with your application. It is also very useful to check that your development server configuration is as similar as possible to the production server. That's why you should inspect the production server configuration at the beginning of a project, and report its PHP settings in a `php.yml` file in your project. You can then develop and test with confidence that you will not encounter any compatibility errors once you deploy your project to the production platform. 562 563 The variables defined under the `set` header are modified (despite how they were defined in the server `php.ini` file). The variables defined under the `warn` category cannot be modified on the fly, but symfony can run even if they are not properly set. It is just considered bad practice to have these settings set to on, and symfony will log a warning in this case. The variables defined under the `check` category cannot be modified on the fly either, but they must have a certain value for symfony to run. So, in this case, an exception is raised if the `php.ini` file is not correct. 564 565 The default php.yml file sets log_errors to on so that you can trace errors in symfony projects. It also recommends that the `register_globals` be set to `off` to prevent security breaches. 566 567 If you don't want symfony to apply these settings, or if you want to run a project with `magic_quotes_gpc` and `register_globals` set to `on` without warning, then create a `php.yml` file in your application `config/` directory, and override the settings you want to change. 568 569 Additionally, if your project requires an extension, you can specify it under the `extensions` category. It expects an array of extension names, as follows: 570 571 extensions: [gd, mysql, mbstring] 572 573 Summary 574 ------- 575 576 The configuration files can heavily modify the way the framework works. Because symfony relies on configuration even for its core features and file loading, it can adapt to many more environments than just the standard dedicated host. This great configurability is one of the main strengths of symfony. Even if it sometimes frightens newcomers, who see in configuration files a lot of conventions to learn, it allows symfony applications to be compatible with a very large number of platforms and environments. Once you become a master of symfony's configuration, no server will ever refuse to run your applications!
titre
Description
Corps
titre
Description
Corps
titre
Description
Corps
titre
Corps
| Généré le : Fri Mar 16 22:42:14 2007 | par Balluche grâce à PHPXref 0.7 |