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