minor #16787 [HtmlSanitizer] Document the new component (wouterj)

javiereguiluz · javiereguiluz · commit 7ba0c87b2f00 · 2022-05-20T16:02:11.000+02:00
This PR was merged into the 6.1 branch. Discussion ---------- [HtmlSanitizer] Document the new component Fixes #16332, fixes #16716, fixes #16804 A first start with the documentation for the new HTML sanitizer component. I'm using the same style as we did in the HttpClient documentation, as I think that worked pretty well. cc `@tgalopin` Commits ------- 5f3cfeb [HTML Sanitizer] Write documentation
diff --git a/html_sanitizer.rst b/html_sanitizer.rst
diff --git a/index.rst b/index.rst
@@ -40,6 +40,7 @@ Topics
     event_dispatcher
     forms
     frontend
+    html_sanitizer
     http_cache
     http_client
     lock
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -1198,6 +1198,17 @@ connection is verified for authenticity. Authenticating the certificate is not
 enough to be sure about the server, so you should combine this with the
 ``verify_host`` option.
 
+html_sanitizer
+~~~~~~~~~~~~~~
+
+.. versionadded:: 6.1
+
+    The HTML sanitizer configuration was introduced in Symfony 6.1.
+
+The ``html_sanitizer`` option (and its children) are used to configure
+custom HTML sanitizers. Read more about the options in the
+:ref:`HTML sanitizer documentation <html-sanitizer-configuration>`.
+
 profiler
 ~~~~~~~~
 
diff --git a/reference/forms/types/options/sanitize_html.rst.inc b/reference/forms/types/options/sanitize_html.rst.inc
@@ -0,0 +1,18 @@
+sanitize_html
+~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+.. versionadded:: 6.1
+
+    The ``sanitize_html`` option was introduced in Symfony 6.1.
+
+When ``true``, the text input will be sanitized using the
+:doc:`Symfony HTML Sanitizer component </html_sanitizer>` after the form is
+submitted. This protects the form input against XSS, clickjacking and CSS
+injection.
+
+.. note::
+
+    You must :ref:`install the HTML sanitizer component <html-sanitizer-installation>`
+    to use this option.
diff --git a/reference/forms/types/options/sanitizer.rst.inc b/reference/forms/types/options/sanitizer.rst.inc
@@ -0,0 +1,11 @@
+sanitizer
+~~~~~~~~~
+
+**type**: ``string`` **default**: ``"default"``
+
+.. versionadded:: 6.1
+
+    The ``sanitizer`` option was introduced in Symfony 6.1.
+
+When `sanitize_html`_ is enabled, you can specify the name of a
+:ref:`custom sanitizer <html-sanitizer-configuration>` using this option.
diff --git a/reference/forms/types/text.rst b/reference/forms/types/text.rst
@@ -57,6 +57,10 @@ an empty string, explicitly set the ``empty_data`` option to an empty string.
 
 .. include:: /reference/forms/types/options/row_attr.rst.inc
 
+.. include:: /reference/forms/types/options/sanitize_html.rst.inc
+
+.. include:: /reference/forms/types/options/sanitizer.rst.inc
+
 .. include:: /reference/forms/types/options/trim.rst.inc
 
 Overridden Options
diff --git a/reference/forms/types/textarea.rst b/reference/forms/types/textarea.rst
@@ -22,6 +22,13 @@ Renders a ``textarea`` HTML element.
     ``<textarea>``, consider using the FOSCKEditorBundle community bundle. Read
     `its documentation`_ to learn how to integrate it in your Symfony application.
 
+.. caution::
+
+    When allowing users to type HTML code in the textarea (or using a
+    WYSIWYG) editor, the application is vulnerable to XSS injection,
+    clickjacking or CSS injection. Use the `sanitize_html`_ option to
+    protect against these types of attacks.
+
 Inherited Options
 -----------------
 
@@ -61,6 +68,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/row_attr.rst.inc
 
+.. include:: /reference/forms/types/options/sanitize_html.rst.inc
+
+.. include:: /reference/forms/types/options/sanitizer.rst.inc
+
 .. include:: /reference/forms/types/options/trim.rst.inc
 
 .. _`its documentation`: https://symfony.com/doc/current/bundles/FOSCKEditorBundle/index.html
diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst
@@ -377,6 +377,25 @@ trans
 Translates the text into the current language. More information in
 :ref:`Translation Filters <translation-filters>`.
 
+sanitize_html
+~~~~~~~~~~~~~
+
+.. versionadded:: 6.1
+
+    The ``sanitize_html()`` filter was introduced in Symfony 6.1.
+
+.. code-block:: twig
+
+    {{ body|sanitize_html(sanitizer = "default") }}
+
+``body``
+    **type**: ``string``
+``sanitizer`` *(optional)*
+    **type**: ``string`` **default**: ``"default"``
+
+Sanitizes the text using the HTML Sanitizer component. More information in
+:ref:`HTML Sanitizer <html-sanitizer-twig>`.
+
 yaml_encode
 ~~~~~~~~~~~
 
