[HtmlSanitizer] Add docs for the new HtmlSanitizer defaultAction config

html_sanitizer.rst

@@ -462,6 +462,80 @@ This can also be used to remove elements from the allow list.
                 ->dropElement('figure')
         );
 
+Default Action
+~~~~~~~~~~~~~~
+
+By default, unconfigured tags are dropped along with their children. If you would rather not lose all children elements by default, you can configure the default action to be ``Block``. Specific elements can still be dropped if needed.
+
+    .. code-block:: yaml
+
+        # config/packages/html_sanitizer.yaml
+        framework:
+            html_sanitizer:
+                sanitizers:
+                    app.post_sanitizer:
+                        # ...
+
+                        # remove all tags by default, but process their children
+                        default_action: 'block'
+                        # remove <figure> and its children
+                        drop_elements: ['figure']
+
+    .. code-block:: xml
+
+        <!-- config/packages/html_sanitizer.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:html-sanitizer>
+                    <!-- remove all tags by default, but process their children -->
+                    <framework:default-action>block</framework:default-action>
+
+                    <!-- remove <figure> and its children -->
+                    <framework:drop-element>figure</framework:drop-element>
+                </framework:html-sanitizer>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        use Symfony\Config\FrameworkConfig;
+
+        return static function (FrameworkConfig $framework): void {
+            $framework->htmlSanitizer()
+                ->sanitizer('app.post_sanitizer')
+                    // remove all tags by default, but process their children
+                    ->defaultAction('block')
+                    // remove <figure> and its children
+                    ->dropElement('figure')
+            ;
+        };
+
+    .. code-block:: php-standalone
+
+        use Symfony\Component\HtmlSanitizer\HtmlSanitizer;
+        use Symfony\Component\HtmlSanitizer\HtmlSanitizerAction;
+        use Symfony\Component\HtmlSanitizer\HtmlSanitizerConfig;
+
+        $postSanitizer = new HtmlSanitizer(
+            (new HtmlSanitizerConfig())
+                // remove all tags by default, but process their children
+                ->defaultAction(HtmlSanitizerAction::Block)
+                // remove <figure> and its children
+                ->dropElement('figure')
+        );
+
+.. note::
+
+    Configuring a default action of ``Allow`` will allow all tags but they will not have any attributes. You probably should still disallow at least ``script`` tags if you want to do this, but generally speaking using an explicit allowlist is going to be much safer.
+
 Allow Attributes
 ~~~~~~~~~~~~~~~~