[HTML Sanitizer] Write documentation

symfony · franckranaivo · May 5, 2022 · May 20, 2022 · May 20, 2022 · May 20, 2022
commit 5f3cfeb3d4f1c654b9d0b1e7dfa0a6880a95b220
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
 ~~~~~~~~
 

@@ -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.
@@ -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.
@@ -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

@@ -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
 ~~~~~~~~~~~