Changeset 8281
- Timestamp:
- 04/04/08 14:13:29 (8 months ago)
- Files:
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
doc/branches/1.1/book/09-Links-and-the-Routing-System.txt
r8255 r8281 435 435 Patterns can contain wildcards (represented by an asterisk, *) and named wildcards (starting with a colon, :). A match to a named wildcard becomes a request parameter value. For instance, the `default` rule defined in Listing 9-15 will match any URL like `/foo/bar`, and set the `module` parameter to `foo` and the `action` parameter to `bar`. And in the `default_symfony` rule, `symfony` is a keyword and `action` is named wildcard parameter. 436 436 437 >**NOTE** 438 >**New in symfony 1.1** named wildcards can be separated by a slash or a dot, so you can write a pattern like: 439 > 440 > my_rule: 441 > url: /foo/:bar.:format 442 > param: { module: mymodule, action: myaction } 443 > 444 >That way, an external URL like 'foo/12.xml' will math `my_rule` and execute `mymodule/muaction` with two parameters: `$bar=12` and `$format=xml`. 445 >You can add more separators by changing the `segment_separators` parameters value in the `sfPatternRouting` factory configuration (see chapter 19). 446 437 447 The routing system parses the `routing.yml` file from the top to the bottom and stops at the first match. This is why you must add your own rules on top of the default ones. For instance, the URL `/foo/123` matches both of the rules defined in Listing 9-16, but symfony first tests `my_rule:`, and as that rule matches, it doesn't even test the `default:` one. The request is handled by the `mymodule/myaction` action with `bar` set to `123` (and not by the `foo/123` action). 438 448 … … 551 561 ### Speeding Up Routing by Using the Rule Name 552 562 553 The link helpers accept a rule label instead of a module/action pair if the rule label is preceded by an atsign (@), as shown in Listing 9-21.563 The link helpers accept a rule label instead of a module/action pair if the rule label is preceded by an 'at' sign (@), as shown in Listing 9-21. 554 564 555 565 Listing 9-21 - Using the Rule Label Instead of the Module/Action … … 563 573 There are pros and cons to this trick. The advantages are as follows: 564 574 565 * The formatting of internal URIs is done muchfaster, since symfony doesn't have to browse all the rules to find the one that matches the link. In a page with a great number of routed hyperlinks, the boost will be noticeable if you use rule labels instead of module/action pairs.575 * The formatting of internal URIs is done faster, since symfony doesn't have to browse all the rules to find the one that matches the link. In a page with a great number of routed hyperlinks, the boost will be noticeable if you use rule labels instead of module/action pairs. 566 576 * Using the rule label helps to abstract the logic behind an action. If you decide to change an action name but keep the URL, a simple change in the `routing.yml` file will suffice. All of the `link_to()` calls will still work without further change. 567 577 * The logic of the call is more apparent with a rule name. Even if your modules and actions have explicit names, it is often better to call `@display_article_by_slug` than `article/display`. … … 573 583 >**TIP** 574 584 >During your tests (in the `dev` environment), if you want to check which rule was matched for a given request in your browser, develop the "logs and msgs" section of the web debug toolbar and look for a line specifying "matched route XXX." You will find more information about the web debug mode in Chapter 16. 585 586 >**NOTE** 587 >**New in symfony 1.1** Routing operations are much faster in production mode, where conversions between external URLs and internal URIs are cached. 575 588 576 589 ### Adding an .html Extension … … 624 637 ); 625 638 626 The sfRouting singletonhas other useful methods for handling routes by hand: `clearRoutes()`, `hasRoutes()` and so on. Refer to the API documentation ([http://www.symfony-project.org/api/symfony.html](http://www.symfony-project.org/api/symfony.html)) to learn more.639 The sfRouting class has other useful methods for handling routes by hand: `clearRoutes()`, `hasRoutes()` and so on. Refer to the API documentation ([http://www.symfony-project.org/api/symfony.html](http://www.symfony-project.org/api/symfony.html)) to learn more. 627 640 628 641 >**TIP** doc/branches/1.1/book/19-Mastering-Symfony-s-Configuration-Files.txt
r8266 r8281 12 12 13 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 14 20 15 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: … … 56 51 `use_database` | Enables the database manager. Set it to `off` if you don't use a database. | `on` 57 52 `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` 58 `use_flash` | Enables the flash parameter feature (see Chapter 6). Set it to `off` if you never use the `setFlash()` method of sfUser. | `on`59 53 `i18n` | Enables interface translation (see Chapter 13). Set it to `on` for multilingual applications. | `off` 60 54 `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` … … 80 74 #### Routing Settings 81 75 82 Two routing settings (see Chapter 9) are stored in `settings.yml`: 76 The routing settings (see Chapter 9) are defined in `factories.yml`, under the `routing` key. Listing 19-1 show the default routing configuration. 77 78 Listing 19-1 - Routing Configuration Settings, in `frontend/config/factories.yml` 79 80 routing: 81 class: sfPatternRouting 82 param: 83 load_configuration: true 84 suffix: . 85 default_module: default 86 default_action: index 87 variable_prefixes: [':'] 88 segment_separators: ['/', '.'] 89 variable_regex: '[\w\d_]+' 90 debug: %SF_DEBUG% 91 logging: %SF_LOGGING_ENABLED% 92 cache: 93 class: sfFileCache 94 param: 95 automatic_cleaning_factor: 0 96 cache_dir: %SF_CONFIG_CACHE_DIR%/routing 97 lifetime: 31556926 98 prefix: %SF_APP_DIR% 83 99 84 100 * 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. 85 * 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. 101 * When a routing rule doesn't define the `module` or the `action` parameter, values from the `factories.yml` are used instead: 102 * `default_module`: Default `module` request parameter. Defaults to the `default` module. 103 * `default_action`: Default `action` request parameter. Defaults to the `index` action. 104 * By default, route patterns identify named wildcards by a colon (`:`) prefix. But if you want to write your rules in a more PHP-friendly syntax, you can add the dollar (`$`) sign in the `variable_prefixes` array. That way, you can write a pattern like '/article/$year/$month/$day/$title' instead of '/article/:year/:month/:day/:title'. 105 * The pattern routing will identify named wildcards between separators. The default separators are the slash and the dot, but you can add more if you want in the `segment_separators` parameter. For instance, if you add the dash (`-`), you can write a pattern like '/article/:year-:month-:day/:title'. 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 108 There is one additional parameter related to routing, but this one is stored in `settings.yml`: 109 * `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. 86 110 87 111 #### Form Validation Settings … … 126 150 #### Miscellaneous Configuration 127 151 128 The `settings.yml` file contains a few more parameters, used internally by symfony for core behaviors. Listing 19- 1lists them as they appear in the configuration file.129 130 Listing 19- 1- Miscellaneous Configuration Settings, in `frontend/config/settings.yml`152 The `settings.yml` file contains a few more parameters, used internally by symfony for core behaviors. Listing 19-2 lists them as they appear in the configuration file. 153 154 Listing 19-2 - Miscellaneous Configuration Settings, in `frontend/config/settings.yml` 131 155 132 156 # Remove comments in core framework classes as defined in the core_compile.yml … … 172 196 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. 173 197 174 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- 2shows the locations used by default and the file syntax.175 176 Listing 19- 2- Default Autoloading Configuration, in `$sf_symfony_data_dir/config/autoload.yml`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-3 shows 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` 177 201 178 202 autoload: … … 268 292 ### The Basic File Structure 269 293 270 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- 3shows a listing of the path variables and the directory they reference.271 272 Listing 19- 3- Default File Structure Variables, from `$sf_symfony_data_dir/config/constants.php`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-4 shows 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` 273 297 274 298 sf_root_dir # myproject/ … … 302 326 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/'`. 303 327 304 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.305 306 Listing 19- 4- Default Module File Structure Variables328 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 Variables 307 331 308 332 sf_app_module_dir # modules/ … … 337 361 ### Modifying the Project Web Root 338 362 339 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- 5. This typically happens when hosting a project on a shared host.340 341 Listing 19- 5- Example of Custom Directory Structure for a Shared Host363 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 Host 342 366 343 367 symfony/ # Private area … … 367 391 ### Linking to Symfony Libraries 368 392 369 The paths to the framework files are defined in the project `config.php` file, as you can see in Listing 19- 6.370 371 Listing 19- 6- The Paths to the Framework Files, in `myproject/config/config.php`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` 372 396 373 397 [php] … … 419 443 ### Default Configuration Handlers 420 444 421 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- 7shows an extract of this file.422 423 Listing 19- 7- Extract of `$sf_symfony_data_dir/config/config_handlers.yml`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-8 shows an extract of this file. 446 447 Listing 19-8 - Extract of `$sf_symfony_data_dir/config/config_handlers.yml` 424 448 425 449 config/settings.yml: … … 462 486 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. 463 487 464 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.465 466 Listing 19- 8- Example of Initialization of the `myMapAPI` Class488 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` Class 467 491 468 492 [php] … … 477 501 user: foobar 478 502 479 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.480 481 Listing 19- 9- A Custom Configuration Handler, in `frontend/lib/myMapConfigHandler.class.php`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-10 - A Custom Configuration Handler, in `frontend/lib/myMapConfigHandler.class.php` 482 506 483 507 [php] … … 551 575 ------------------------ 552 576 553 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 0shows the default `php.yml` file.554 555 Listing 19-1 0- Default PHP Settings for Symfony, in `$sf_symfony_data_dir/config/php.yml`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-11 shows the default `php.yml` file. 578 579 Listing 19-11 - Default PHP Settings for Symfony, in `$sf_symfony_data_dir/config/php.yml` 556 580 557 581 set:
