1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
``escape``
==========
The ``escape`` filter escapes a string using strategies that depend on the
context.
By default, it uses the HTML escaping strategy:
.. code-block:: html+twig
<p>
{{ user.username|escape }}
</p>
For convenience, the ``e`` filter is defined as an alias:
.. code-block:: html+twig
<p>
{{ user.username|e }}
</p>
The ``escape`` filter can also be used in other contexts than HTML thanks to
an optional argument which defines the escaping strategy to use:
.. code-block:: twig
{{ user.username|e }}
{# is equivalent to #}
{{ user.username|e('html') }}
And here is how to escape variables included in JavaScript code:
.. code-block:: twig
{{ user.username|escape('js') }}
{{ user.username|e('js') }}
The ``escape`` filter supports the following escaping strategies for HTML
documents:
* ``html``: escapes a string for the **HTML body** context,
or for HTML attributes values **inside quotes**.
* ``js``: escapes a string for the **JavaScript** context. This is intended for
use in JavaScript or JSON strings, and encodes values using backslash escape
sequences.
* ``css``: escapes a string for the **CSS** context. CSS escaping can be
applied to any string being inserted into CSS and escapes everything except
alphanumerics.
* ``url``: escapes a string for the **URI or parameter** contexts. This should
not be used to escape an entire URI; only a subcomponent being inserted.
* ``html_attr``: escapes a string for the **HTML attribute** context,
**without quotes** around HTML attribute values.
Note that doing contextual escaping in HTML documents is hard and choosing the
right escaping strategy depends on a lot of factors. Please, read related
documentation like `the OWASP prevention cheat sheet
<https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.md>`_
to learn more about this topic.
.. note::
Internally, ``escape`` uses the PHP native `htmlspecialchars`_ function
for the HTML escaping strategy.
.. caution::
When using automatic escaping, Twig tries to not double-escape a variable
when the automatic escaping strategy is the same as the one applied by the
escape filter; but that does not work when using a variable as the
escaping strategy:
.. code-block:: twig
{% set strategy = 'html' %}
{% autoescape 'html' %}
{{ var|escape('html') }} {# won't be double-escaped #}
{{ var|escape(strategy) }} {# will be double-escaped #}
{% endautoescape %}
When using a variable as the escaping strategy, you should disable
automatic escaping:
.. code-block:: twig
{% set strategy = 'html' %}
{% autoescape 'html' %}
{{ var|escape(strategy)|raw }} {# won't be double-escaped #}
{% endautoescape %}
.. tip::
The ``html_attr`` escaping strategy can be useful when you need to
escape a **dynamic HTML attribute name**:
.. code-block:: html+twig
<p {{ your_html_attr|e('html_attr') }}="attribute value">
It can also be used for escaping a **dynamic HTML attribute value**
if it is not quoted, but this is **less performant**.
Instead, it is recommended to quote the HTML attribute value and use
the ``html`` escaping strategy:
.. code-block:: html+twig
<p data-content="{{ content|e('html') }}">
{# is equivalent to, but is less performant #}
<p data-content={{ content|e('html_attr') }}>
Custom Escapers
---------------
.. versionadded:: 3.10
The ``EscaperRuntime`` class has been added in 3.10. On previous versions,
you can define custom escapers by calling the ``setEscaper()`` method on
the escaper extension instance. The first argument is the escaper strategy
(to be used in the ``escape`` call) and the second one must be a valid PHP
callable::
use Twig\Extension\EscaperExtension;
$twig = new \Twig\Environment($loader);
$twig->getExtension(EscaperExtension::class)->setEscaper('csv', 'csv_escaper');
When called by Twig, the callable receives the Twig environment instance,
the string to escape, and the charset.
You can define custom escapers by calling the ``setEscaper()`` method on the
escaper runtime instance. It accepts two arguments: the strategy name and a PHP
callable that accepts a string to escape and the charset::
use Twig\Runtime\EscaperRuntime;
$twig = new \Twig\Environment($loader);
$escaper = fn ($string, $charset) => $string;
$twig->getRuntime(EscaperRuntime::class)->setEscaper('identity', $escaper);
# Usage in a template:
# {{ 'Twig'|escape('identity') }}
.. note::
Built-in escapers cannot be overridden mainly because they should be
considered as the final implementation and also for better performance.
Arguments
---------
* ``strategy``: The escaping strategy
* ``charset``: The string charset
.. _`htmlspecialchars`: https://www.php.net/htmlspecialchars
|
