Matthias Andreas Benkard | 12a5735 | 2021-12-28 18:02:04 +0100 | [diff] [blame] | 1 | ``escape`` |
| 2 | ========== |
| 3 | |
| 4 | The ``escape`` filter escapes a string using strategies that depend on the |
| 5 | context. |
| 6 | |
| 7 | By default, it uses the HTML escaping strategy: |
| 8 | |
| 9 | .. code-block:: html+twig |
| 10 | |
| 11 | <p> |
| 12 | {{ user.username|escape }} |
| 13 | </p> |
| 14 | |
| 15 | For convenience, the ``e`` filter is defined as an alias: |
| 16 | |
| 17 | .. code-block:: html+twig |
| 18 | |
| 19 | <p> |
| 20 | {{ user.username|e }} |
| 21 | </p> |
| 22 | |
| 23 | The ``escape`` filter can also be used in other contexts than HTML thanks to |
| 24 | an optional argument which defines the escaping strategy to use: |
| 25 | |
| 26 | .. code-block:: twig |
| 27 | |
| 28 | {{ user.username|e }} |
| 29 | {# is equivalent to #} |
| 30 | {{ user.username|e('html') }} |
| 31 | |
| 32 | And here is how to escape variables included in JavaScript code: |
| 33 | |
| 34 | .. code-block:: twig |
| 35 | |
| 36 | {{ user.username|escape('js') }} |
| 37 | {{ user.username|e('js') }} |
| 38 | |
| 39 | The ``escape`` filter supports the following escaping strategies for HTML |
| 40 | documents: |
| 41 | |
| 42 | * ``html``: escapes a string for the **HTML body** context. |
| 43 | |
| 44 | * ``js``: escapes a string for the **JavaScript** context. |
| 45 | |
| 46 | * ``css``: escapes a string for the **CSS** context. CSS escaping can be |
| 47 | applied to any string being inserted into CSS and escapes everything except |
| 48 | alphanumerics. |
| 49 | |
| 50 | * ``url``: escapes a string for the **URI or parameter** contexts. This should |
| 51 | not be used to escape an entire URI; only a subcomponent being inserted. |
| 52 | |
| 53 | * ``html_attr``: escapes a string for the **HTML attribute** context. |
| 54 | |
| 55 | Note that doing contextual escaping in HTML documents is hard and choosing the |
| 56 | right escaping strategy depends on a lot of factors. Please, read related |
| 57 | documentation like `the OWASP prevention cheat sheet |
| 58 | <https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.md>`_ |
| 59 | to learn more about this topic. |
| 60 | |
| 61 | .. note:: |
| 62 | |
| 63 | Internally, ``escape`` uses the PHP native `htmlspecialchars`_ function |
| 64 | for the HTML escaping strategy. |
| 65 | |
| 66 | .. caution:: |
| 67 | |
| 68 | When using automatic escaping, Twig tries to not double-escape a variable |
| 69 | when the automatic escaping strategy is the same as the one applied by the |
| 70 | escape filter; but that does not work when using a variable as the |
| 71 | escaping strategy: |
| 72 | |
| 73 | .. code-block:: twig |
| 74 | |
| 75 | {% set strategy = 'html' %} |
| 76 | |
| 77 | {% autoescape 'html' %} |
| 78 | {{ var|escape('html') }} {# won't be double-escaped #} |
| 79 | {{ var|escape(strategy) }} {# will be double-escaped #} |
| 80 | {% endautoescape %} |
| 81 | |
| 82 | When using a variable as the escaping strategy, you should disable |
| 83 | automatic escaping: |
| 84 | |
| 85 | .. code-block:: twig |
| 86 | |
| 87 | {% set strategy = 'html' %} |
| 88 | |
| 89 | {% autoescape 'html' %} |
| 90 | {{ var|escape(strategy)|raw }} {# won't be double-escaped #} |
| 91 | {% endautoescape %} |
| 92 | |
| 93 | Custom Escapers |
| 94 | --------------- |
| 95 | |
| 96 | You can define custom escapers by calling the ``setEscaper()`` method on the |
| 97 | escaper extension instance. The first argument is the escaper name (to be |
| 98 | used in the ``escape`` call) and the second one must be a valid PHP callable:: |
| 99 | |
| 100 | $twig = new \Twig\Environment($loader); |
| 101 | $twig->getExtension(\Twig\Extension\EscaperExtension::class)->setEscaper('csv', 'csv_escaper'); |
| 102 | |
| 103 | When called by Twig, the callable receives the Twig environment instance, the |
| 104 | string to escape, and the charset. |
| 105 | |
| 106 | .. note:: |
| 107 | |
| 108 | Built-in escapers cannot be overridden mainly because they should be |
| 109 | considered as the final implementation and also for better performance. |
| 110 | |
| 111 | Arguments |
| 112 | --------- |
| 113 | |
| 114 | * ``strategy``: The escaping strategy |
| 115 | * ``charset``: The string charset |
| 116 | |
| 117 | .. _`htmlspecialchars`: https://secure.php.net/htmlspecialchars |