Changeset 8317
- Timestamp:
- 04/05/08 16:48:24 (3 months ago)
- Files:
-
- doc/branches/1.1/book/12-Caching.txt (modified) (1 diff)
- doc/branches/1.1/book/13-I18n-and-L10n.txt (modified) (1 diff)
- doc/branches/1.1/book/19-Mastering-Symfony-s-Configuration-Files.txt (modified) (12 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
doc/branches/1.1/book/12-Caching.txt
r8283 r8317 252 252 > cacheDir: %SF_TEMPLATE_CACHE_DIR% 253 253 > 254 >You can replace the `class` with your own cache storage class or with one of the symfony alternative classes (including `sfAPCCache`, `sfEAcceleratorCache`, `sfMemcacheCache`, `sfSQLiteCache`, and `sfXCacheCache`). The parameters defined under the `param` key are passed to the constructor of the cache class as an associative array. Any view cache storage class must implement all methods found in the abstract `sfCache` class. Refer to the API documentation ([http://www. symfony-project.com/api/symfony.html](http://www. symfony-project.com/api/symfony.html))for more information on this subject.254 >You can replace the `class` with your own cache storage class or with one of the symfony alternative classes (including `sfAPCCache`, `sfEAcceleratorCache`, `sfMemcacheCache`, `sfSQLiteCache`, and `sfXCacheCache`). The parameters defined under the `param` key are passed to the constructor of the cache class as an associative array. Any view cache storage class must implement all methods found in the abstract `sfCache` class. Refer to the Chapter 19 for more information on this subject. 255 255 256 256 ### Using the Super Fast Cache doc/branches/1.1/book/13-I18n-and-L10n.txt
r8283 r8317 343 343 If additional translations need to be done, simply add a new `messages.``XX``.xml` translation file in the same directory. 344 344 345 >**TIP** 346 >As looking for dictionary files, parsing them, and finding the correct translation for a given string takes some time, symfony uses an internal cache to speedup the process. By default, this cache uses the filesystem. You can configure how the i18N cache works (for instance, to share the cache between several servers) in the `factories.yml` (see Chapter 19). 347 345 348 ### Managing Dictionaries 346 349 doc/branches/1.1/book/19-Mastering-Symfony-s-Configuration-Files.txt
r8283 r8317 106 106 * The pattern routing uses its own cache, in production mode, to speed up conversions between external URLs and internal URIs. By default, this cache uses the filesystem, but you can use any cache class, provided that you declare the class and its settings in the `cache` parameter. See Chapter 15 for the list of available cache storage classes. To deactivate the routing cache in production, set the `debug` parameter to `on`. 107 107 108 These are only the settings for the `sfPatternRouting` class. You can use another class for your application routing, either your own or one of symfony's routing factories (`sfNoRouting` and `sfPathInfoRouting`). With either of these two factories, all external URLs look like 'module/action?key1=param1'. No customization possible--but it's fast. The difference is that the first uses PHP's `GET`, and the second uses `PATH_INFO`. Use them mainly for backend interfaces. 109 108 110 There is one additional parameter related to routing, but this one is stored in `settings.yml`: 109 111 * `no_script_name` enables the front controller name in generated URLs. The `no_script_name` setting can be on only for a single application in a project, unless you store the front controllers in various directories and alter the default URL rewriting rules. It is usually on for the production environment of your main application and off for the others. … … 117 119 #### Cache Settings 118 120 119 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). 121 Cache settings are defined in `cache.yml` for the most part, except for two in `settings.yml`: `cache` enables the template cache mechanism, and `etag` enables ETag handling on the server side (see Chapter 15). You can also specify which storage to use for two all cache systems (the view cache, the routing cache, and the i19n cache) in `factories.yml`. Listing 19-2 show the default view cache factory configuration. 122 123 Listing 19-2 - View Cache Configuration Settings, in `frontend/config/factories.yml` 124 125 view_cache: 126 class: sfFileCache 127 param: 128 automatic_cleaning_factor: 0 129 cache_dir: %SF_TEMPLATE_CACHE_DIR% 130 lifetime: 86400 131 prefix: %SF_APP_DIR%/template 132 133 The `class` can be any of `sfFileCache`, `sfAPCCache`, `sfEAcceleratorCache`, `sfXCacheCache`, `sfMemcacheCache`, and `sfSQLiteCache`. It can also be your own custom class, provided it extends `sfCache` and provides the same generic methods for setting, retrieving and deleting a key in the cache. The factory parameters depend on the class you choose, but there are constants: 134 135 * `lifetime` defines the number of seconds after which a cache part is removed 136 * `prefix` is a prefix added to every cache key. Use the same prefix for two applications if you want their cache to be shared. 137 138 Then, for each particular factory, you have to define the location of the cache storage. 139 140 * for `sfFileCache`, the `cache_dir` parameter locates the absolute path to the cache directory 141 * `sfAPCCache`, `sfEAcceleratorCache`, and `sfXCacheCache` don't take any location parameter, since they use PHP native functions for communicating with APC, EAccelerator or the XCache cache systems 142 * for `sfMemcacheCache`, enter the hostname of the Memcached server in the `host` parameter, or an array of hosts in the `servers` parameter 143 * for `sfSQLiteCache`, the absolute path to the SQLite database file should be entered in the `database` parameter 144 145 For additional parameters, check the API documentation of each cache class. 146 147 The view is not the only component to be able to use a cache. Both the `routing` and the `I18N` factories offer a `cache` parameter in which you can set any cache factory, just like the view cache. For instance, Listing 19-1 shows of the routing uses the file cache for its speedup tactics by default, but you can change it to whatever you want. 120 148 121 149 #### Logging Settings … … 150 178 #### Miscellaneous Configuration 151 179 152 The `settings.yml` file contains a few more parameters, used internally by symfony for core behaviors. Listing 19- 2lists them as they appear in the configuration file.153 154 Listing 19- 2- Miscellaneous Configuration Settings, in `frontend/config/settings.yml`180 The `settings.yml` file contains a few more parameters, used internally by symfony for core behaviors. Listing 19-3 lists them as they appear in the configuration file. 181 182 Listing 19-3 - Miscellaneous Configuration Settings, in `frontend/config/settings.yml` 155 183 156 184 # Remove comments in core framework classes as defined in the core_compile.yml … … 196 224 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. 197 225 198 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- 3shows the locations used by default and the file syntax.199 200 Listing 19- 3- Default Autoloading Configuration, in `$sf_symfony_data_dir/config/autoload.yml`226 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-4 shows the locations used by default and the file syntax. 227 228 Listing 19-4 - Default Autoloading Configuration, in `$sf_symfony_data_dir/config/autoload.yml` 201 229 202 230 autoload: … … 292 320 ### The Basic File Structure 293 321 294 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- 4shows a listing of the path variables and the directory they reference.295 296 Listing 19- 4- Default File Structure Variables, from `$sf_symfony_data_dir/config/constants.php`322 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-5 shows a listing of the path variables and the directory they reference. 323 324 Listing 19-5 - Default File Structure Variables, from `$sf_symfony_data_dir/config/constants.php` 297 325 298 326 sf_root_dir # myproject/ … … 326 354 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/'`. 327 355 328 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- 5.329 330 Listing 19- 5- Default Module File Structure Variables356 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-6. 357 358 Listing 19-6 - Default Module File Structure Variables 331 359 332 360 sf_app_module_dir # modules/ … … 361 389 ### Modifying the Project Web Root 362 390 363 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 `web/` 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- 6. This typically happens when hosting a project on a shared host.364 365 Listing 19- 6- Example of Custom Directory Structure for a Shared Host391 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 `web/` 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-7. This typically happens when hosting a project on a shared host. 392 393 Listing 19-7 - Example of Custom Directory Structure for a Shared Host 366 394 367 395 symfony/ # Private area … … 391 419 ### Linking to Symfony Libraries 392 420 393 The paths to the framework files are defined in the project `config.php` file, as you can see in Listing 19- 7.394 395 Listing 19- 7- The Paths to the Framework Files, in `myproject/config/config.php`421 The paths to the framework files are defined in the project `config.php` file, as you can see in Listing 19-8. 422 423 Listing 19-8 - The Paths to the Framework Files, in `myproject/config/config.php` 396 424 397 425 [php] … … 443 471 ### Default Configuration Handlers 444 472 445 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- 8shows an extract of this file.446 447 Listing 19- 8- Extract of `$sf_symfony_data_dir/config/config_handlers.yml`473 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-9 shows an extract of this file. 474 475 Listing 19-9 - Extract of `$sf_symfony_data_dir/config/config_handlers.yml` 448 476 449 477 config/settings.yml: … … 486 514 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. 487 515 488 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- 9.489 490 Listing 19- 9- Example of Initialization of the `myMapAPI` Class516 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-10. 517 518 Listing 19-10 - Example of Initialization of the `myMapAPI` Class 491 519 492 520 [php] … … 501 529 user: foobar 502 530 503 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-10.504 505 Listing 19-1 0- A Custom Configuration Handler, in `frontend/lib/myMapConfigHandler.class.php`531 In order to transform these settings into code equivalent to Listing 19-9, 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-11. 532 533 Listing 19-11 - A Custom Configuration Handler, in `frontend/lib/myMapConfigHandler.class.php` 506 534 507 535 [php] … … 575 603 ------------------------ 576 604 577 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-1 1shows the default `php.yml` file.578 579 Listing 19-1 1- Default PHP Settings for Symfony, in `$sf_symfony_data_dir/config/php.yml`605 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-12 shows the default `php.yml` file. 606 607 Listing 19-12 - Default PHP Settings for Symfony, in `$sf_symfony_data_dir/config/php.yml` 580 608 581 609 set:
