[TwigBundle] Document twig.safe_class resource tag

reference/dic_tags.rst

@@ -1247,6 +1247,55 @@ the service is auto-registered and auto-tagged. But, you can also register it ma
             ],
         ]);
 
+.. _dic_tags-twig-safe-class:
+
+twig.safe_class
+---------------
+
+**Purpose**: Mark a class as safe for Twig's escaper
+
+.. versionadded:: 8.1
+
+    The ``twig.safe_class`` resource tag was introduced in Symfony 8.1.
+
+When a value of the tagged class is printed by a Twig template, Twig treats
+it as already safe for the configured escaping strategies and skips
+re-escaping it. This is useful for value objects that already contain
+pre-escaped or otherwise trusted output (e.g. an ``HtmlString`` wrapper)
+without having to call the ``raw`` filter at every call site.
+
+Unlike most service tags, ``twig.safe_class`` is a
+:ref:`resource tag <service-tags-resource-tags>`: it is attached to the class
+definition, not to a service.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\Twig\HtmlString:
+                resource_tags:
+                    - { name: twig.safe_class, strategy: html }
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use App\Twig\HtmlString;
+
+        return function (ContainerConfigurator $container): void {
+            $container->services()
+                ->set(HtmlString::class)
+                    ->resourceTag('twig.safe_class', ['strategy' => 'html']);
+        };
+
+The ``strategy`` attribute is required and accepts a string (single strategy)
+or a list of strings (multiple strategies). Supported values are ``html``,
+``js``, ``css``, ``url``, ``html_attr`` and ``html_attr_relaxed``. The same
+class can be tagged several times to mark it safe for several strategies.
+
 validator.constraint_validator
 ------------------------------
 

service_container/tags.rst

@@ -247,6 +247,8 @@ call to support ``ReflectionMethod``::
     :method:`Symfony\\Component\\DependencyInjection\\ContainerBuilder::registerAttributeForAutoconfiguration`
     callable.
 
+.. _service-tags-resource-tags:
+
 Tagging Non-Service Classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

templates.rst

@@ -1267,6 +1267,13 @@ use the `Twig raw filter`_ to disable the output escaping for that variable:
 Read the `Twig output escaping docs`_ to learn more about how to disable output
 escaping for a block or even an entire template.
 
+.. tip::
+
+    Value objects that hold pre-escaped or trusted content (typically shipped
+    by bundles, but applications can do the same) can be marked as safe so
+    Twig won't re-escape them, using the
+    :ref:`twig.safe_class <dic_tags-twig-safe-class>` resource tag.
+
 .. _templates-namespaces:
 
 Template Namespaces