Changeset 8266
- Timestamp:
- 04/04/08 11:59:19 (3 months ago)
- Files:
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
doc/branches/1.1/book/07-Inside-the-View-Layer.txt
r8253 r8266 916 916 <script>alert(document.cookie)</script> 917 917 918 You could escape your output manually by enclosing every unsure value in a call to `html entities()`, but that approach would be very repetitive and error-prone. Instead, symfony provides a special system, called output escaping, which automatically escapes every variable output in a template. It is activated by a simple parameter in the application `settings.yml`.918 You could escape your output manually by enclosing every unsure value in a call to `htmlspeciachars()`, but that approach would be very repetitive and error-prone. Instead, symfony provides a special system, called output escaping, which automatically escapes every variable output in a template. It is activated by a simple parameter in the application `settings.yml`. 919 919 920 920 ### Activating Output Escaping … … 922 922 Output escaping is configured globally for an application in the `settings.yml` file. Two parameters control the way that output escaping works: the strategy determines how the variables are made available to the view, and the method is the default escaping function applied to the data. 923 923 924 The next sections describe these settings in detail but, basically, all you need to do to activate output escaping is to set the `escaping_strategy` parameter to `both` instead of its default value `bc`, as shown in Listing 7-42.924 Basically, all you need to do to activate output escaping is to set the `escaping_strategy` parameter to `on` instead of its default value `off`, as shown in Listing 7-42. 925 925 926 926 Listing 7-42 - Activating Output Escaping, in `frontend/config/settings.yml` … … 928 928 all: 929 929 .settings: 930 escaping_strategy: both931 escaping_method: ESC_ ENTITIES932 933 This will add `html entities()` to all variable output by default. For instance, suppose that you define a `test` variable in an action as follows:930 escaping_strategy: on 931 escaping_method: ESC_SPECIALCHARS 932 933 This will add `htmlspecialchars()` to all variable output by default. For instance, suppose that you define a `test` variable in an action as follows: 934 934 935 935 [php] … … 940 940 [php] 941 941 echo $test; 942 => & gt;<script>alert(document.cookie)</script>943 944 Activating output escaping also gives access to an `$sf_data` variable in every template. Itis a container object referencing all the escaped variables. So you can also output the test variable with the following:942 => <script>alert(document.cookie)</script> 943 944 In addition, every template has access to an `$sf_data` variable, which is a container object referencing all the escaped variables. So you can also output the test variable with the following: 945 945 946 946 [php] 947 947 echo $sf_data->get('test'); 948 => & gt;<script>alert(document.cookie)</script>948 => <script>alert(document.cookie)</script> 949 949 950 950 >**TIP** 951 951 >The $sf_data object implements the Array interface, so instead of using the `$sf_data->get('myvariable')`, you can retrieve escaped values by calling `$sf_data['myvariable']`. But it is not a real array, so functions like `print_r()` will not work as expected. 952 952 953 This objectalso gives you access to the unescaped, or raw, data. This is useful when a variable stores HTML code meant to be interpreted by the browser, provided that you trust this variable. Call the `getRaw()` method when you need to output the raw data.953 `$sf_data` also gives you access to the unescaped, or raw, data. This is useful when a variable stores HTML code meant to be interpreted by the browser, provided that you trust this variable. Call the `getRaw()` method when you need to output the raw data. 954 954 955 955 [php] … … 959 959 You will have to access raw data each time you need variables containing HTML to be really interpreted as HTML. You can now understand why the default layout uses `$sf_data->getRaw('sf_content')` to include the template, rather than a simpler `$sf_content`, which breaks when output escaping is activated. 960 960 961 ### Escaping Strategy 962 963 The `escaping_strategy` setting determines the way variables are output by default. The following are the possible values: 964 965 * `bc` (backward compatible mode): Variables are not escaped, but an escaped version of each variable is available through the `$sf_data` container. So the data is raw by default, unless you choose to use the escaped value via the `$sf_data` object. This is the default value, and you should be aware that with this strategy, your application is subject to XSS attack risks. 966 * `both`: All variables are escaped by default. Values are also made available in the `$sf_data` container. This is the recommended strategy, since you will be at risk only if you voluntarily output raw data. In some cases, you will have to use unescaped data--for instance, if you output a variable that contains HTML with the intention that this HTML be rendered as such in the browser. So be aware that if you switch to this strategy with a partially developed application, some features may break. The best choice is to use this setting right from the beginning. 967 * `on`: Values are available only in the `$sf_data` container. This is the most secure and fastest way to deal with escaping, because each time you output a variable, you must choose if you want to use the escaped version with `get()` or the raw version with `getRaw()`. So you are always aware of the possibility that data may be corrupted. 968 * `off`: Turns off output escaping. The `$sf_data` container is not available in templates. You can choose to use this strategy rather than `bc` to speed up your application if you are sure that you will never need to access escaped data. 961 When `escaping_strategy` is `off`, `$sf_data` is still available, but it always returns raw data. 962 963 >**TIP** 964 >Symfony 1.0 had two other possible values for `escaping_strategy`. `bc` now fallbacks to `off`, and `both` now fallbacks to `on`. Using any of these values still work, but will log an error. 969 965 970 966 ### Escaping Helpers … … 973 969 974 970 * `ESC_RAW`: Doesn't escape the value. 971 * `ESC_SPECIALCHARS`: Applies the PHP function `htmlspecialchars()` to the input. 975 972 * `ESC_ENTITIES`: Applies the PHP function `htmlentities()` to the input with `ENT_QUOTES` as the quote style. 976 973 * `ESC_JS`: Escapes a value to be put into a JavaScript string that is going to be used as HTML. This is useful for escaping things where HTML is going to be dynamically changed using JavaScript. … … 979 976 ### Escaping Arrays and Objects 980 977 981 Output escaping not only works for strings, but also for arrays and objects. Any values that are objects or arrays will pass on their escaped state to their children. Assuming your strategy is set to ` both`, Listing 7-43 demonstrates the escaping cascade.978 Output escaping not only works for strings, but also for arrays and objects. Any values that are objects or arrays will pass on their escaped state to their children. Assuming your strategy is set to `on`, Listing 7-43 demonstrates the escaping cascade. 982 979 983 980 Listing 7-43 - Escaping Also Works for Arrays and Objects … … 1016 1013 => sfOutputEscaperObjectDecorator 1017 1014 1018 This explains why some usual PHP functions (like `array_shift()`, `print_r()`, and so on) don't work on escaped arrays anymore. But they can be still be accessed using `[]`, be traversed using foreach, and they give back the right result with `count()` (`count()` works only with PHP 5.2 or later). And in templates, the data should be read-only anyway, so most access will be through the methods that do work.1015 This explains why some usual PHP functions (like `array_shift()`, `print_r()`, and so on) don't work on escaped arrays anymore. But they can be still be accessed using `[]`, be traversed using `foreach`, and they give back the right result with `count()` (`count()` works only with PHP 5.2 or later). And in templates, the data should be read-only anyway, so most access will be through the methods that do work. 1019 1016 1020 1017 You still have a way to retrieve the raw data through the `$sf_data` object. In addition, methods of escaped objects are altered to accept an additional parameter: an escaping method. So you can choose an alternative escaping method each time you display a variable in a template, or opt for the `ESC_RAW` helper to deactivate escaping. See Listing 7-44 for an example. doc/branches/1.1/book/18-Performance.txt
r7705 r8266 544 544 auto_start: false 545 545 546 The same applies for the database (as explained in the "Tweaking the Model" section earlier in this chapter) and output escaping feature (see Chapter 7). If your application makes no use of them, deactivate themfor a small performance gain, this time in the `settings.yml` file (see Listing 18-20).547 548 Listing 18-20 - Turning Features Off, in `frontend/config/settings.yml`546 The same applies for the database feature (as explained in the "Tweaking the Model" section earlier in this chapter). If your application makes no use of a database, deactivate it for a small performance gain, this time in the `settings.yml` file (see Listing 18-20). 547 548 Listing 18-20 - Turning Database Features Off, in `frontend/config/settings.yml` 549 549 550 550 all: 551 551 .settings: 552 552 use_database: off # Database and model features 553 escaping_strategy: off # Output escaping feature554 553 555 554 As for the security features (see Chapter 6), you can deactivate them in the `filters.yml` file, as shown in Listing 18-21. doc/branches/1.1/book/19-Mastering-Symfony-s-Configuration-Files.txt
r7705 r8266 59 59 `i18n` | Enables interface translation (see Chapter 13). Set it to `on` for multilingual applications. | `off` 60 60 `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` 61 `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`61 `escaping_strategy` | Enables the output escaping feature (see Chapter 7). Set it to `on` if you want data passed to your templates to be escaped. | `off` 62 62 `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 63 63 `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 … … 75 75 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: 76 76 77 * The `escaping_strategy` setting can take the value `bc`, `both`,`on`, or `off`.78 * The escaping_method setting can be set to `ESC_RAW`, `ESC_ ENTITIES`, `ESC_JS`, or `ESC_JS_NO_ENTITIES`.77 * The `escaping_strategy` setting can take the value`on`, or `off`. 78 * The escaping_method setting can be set to `ESC_RAW`, `ESC_SPECIALCHARS`, `ESC_ENTITIES`, `ESC_JS`, or `ESC_JS_NO_ENTITIES`. 79 79 80 80 #### Routing Settings
