1``escape``
2==========
3
4The ``escape`` filter escapes a string using strategies that depend on the
5context.
6
7By default, it uses the HTML escaping strategy:
8
9.. code-block:: html+twig
10
11    <p>
12        {{ user.username|escape }}
13    </p>
14
15For 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
23The ``escape`` filter can also be used in other contexts than HTML thanks to
24an 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
32And 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
39The ``escape`` filter supports the following escaping strategies for HTML
40documents:
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
55Note that doing contextual escaping in HTML documents is hard and choosing the
56right escaping strategy depends on a lot of factors. Please, read related
57documentation like `the OWASP prevention cheat sheet
58<https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.md>`_
59to 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
93Custom Escapers
94---------------
95
96You can define custom escapers by calling the ``setEscaper()`` method on the
97escaper extension instance. The first argument is the escaper name (to be
98used 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
103When called by Twig, the callable receives the Twig environment instance, the
104string 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
111Arguments
112---------
113
114* ``strategy``: The escaping strategy
115* ``charset``:  The string charset
116
117.. _`htmlspecialchars`: https://secure.php.net/htmlspecialchars
118