From a83f7e855d07cb0c855904cdc83db55d318e6119 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Mon, 22 Apr 2019 09:02:23 +0200 Subject: [PATCH] added a note about escaping --- doc/filters/escape.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/filters/escape.rst b/doc/filters/escape.rst index 1a41d0985f3..fd8041fd925 100644 --- a/doc/filters/escape.rst +++ b/doc/filters/escape.rst @@ -8,7 +8,7 @@ .. versionadded:: 1.14.0 The ability to define custom escapers was added in Twig 1.14.0. -The ``escape`` filter escapes a string for safe insertion into the final +The ``escape`` filter escapes a string for safe insertion into the final HTML output. It supports different escaping strategies depending on the template context. @@ -40,21 +40,28 @@ And here is how to escape variables included in JavaScript code: {{ user.username|escape('js') }} {{ user.username|e('js') }} -The ``escape`` filter supports the following escaping strategies: +The ``escape`` filter supports the following escaping strategies for HTML +documents: * ``html``: escapes a string for the **HTML body** context. -* ``js``: escapes a string for the **JavaScript context**. +* ``js``: escapes a string for the **JavaScript** context. -* ``css``: escapes a string for the **CSS context**. CSS escaping can be +* ``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 +* ``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. +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 +`_ +to learn more about this topic. + .. note:: Internally, ``escape`` uses the PHP native `htmlspecialchars`_ function