diff --git a/html_sanitizer.rst b/html_sanitizer.rst index b7fcec49cec..4a322f5aea8 100644 --- a/html_sanitizer.rst +++ b/html_sanitizer.rst @@ -473,6 +473,100 @@ This can also be used to remove elements from the allow list. ->dropElement('figure') ); +.. _html-sanitizer-default-action: + +Default Action for Unconfigured Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 7.2 + + The ``defaultAction()`` method was introduced in Symfony 7.2. + +By default, elements that are not explicitly allowed, blocked, or dropped +will be removed along with their children. You can change this behavior +by configuring the default action using the ``defaultAction()`` method. + +The method accepts an ``HtmlSanitizerAction`` enum with three possible values: + +* ``HtmlSanitizerAction::Drop`` (default): Remove the element and its children +* ``HtmlSanitizerAction::Block``: Remove the element but keep its children +* ``HtmlSanitizerAction::Allow``: Keep the element (without any attributes) + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/html_sanitizer.yaml + framework: + html_sanitizer: + sanitizers: + app.post_sanitizer: + # set the default action for unconfigured elements + default_action: 'block' # or 'allow', 'drop' + allow_elements: + p: '*' + + .. code-block:: xml + + + + + + + + + + + * + + + + + + + .. code-block:: php + + // config/packages/framework.php + use Symfony\Config\FrameworkConfig; + + return static function (FrameworkConfig $framework): void { + $framework->htmlSanitizer() + ->sanitizer('app.post_sanitizer') + // set the default action for unconfigured elements + ->defaultAction('block') // or 'allow', 'drop' + ->allowElement('p', '*') + ; + }; + + .. code-block:: php-standalone + + use Symfony\Component\HtmlSanitizer\HtmlSanitizer; + use Symfony\Component\HtmlSanitizer\HtmlSanitizerAction; + use Symfony\Component\HtmlSanitizer\HtmlSanitizerConfig; + + $postSanitizer = new HtmlSanitizer( + (new HtmlSanitizerConfig()) + // set the default action for unconfigured elements + ->defaultAction(HtmlSanitizerAction::Block) + ->allowElement('p') + ); + +With this configuration, if the input HTML contains an element that is not +explicitly configured (e.g., ````), the sanitizer will remove the +```` element but keep its children, instead of dropping both the +element and its children. + +.. note:: + + When using ``HtmlSanitizerAction::Allow`` as the default action, the + unconfigured elements will be preserved but without any attributes for + security reasons. + Allow Attributes ~~~~~~~~~~~~~~~~