feature #4178 Constant expr as final (fabpot)

This PR was squashed before being merged into the 3.x branch.

Discussion
----------

Constant expr as final

Closes #4119

Commits
-------

230e31d3 Add a recipe about how to mark a node as safe
693693ba Mark ConstantExpression as `@final`

CHANGELOG

@@ -1,5 +1,6 @@
 # 3.11.0 (2024-XX-XX)
 
+ * Mark `ConstantExpression` as being `@final`
  * Add the `find` filter
  * Fix optimizer mode validation in `OptimizerNodeVisitor`
  * Add the possibility to yield from a generator in `PrintNode`

doc/recipes.rst

@@ -528,4 +528,15 @@ include in your templates:
             'tag_variable' => ['{[', ']}'],
         ]));
 
+Marking a Node as being safe
+----------------------------
+
+When using the escaper extension, you might want to mark some nodes as being
+safe to avoid any escaping. You can do so by wrapping your expression with a
+``RawFilter`` node::
+
+    use Twig\Node\Expression\Filter\RawFilter;
+
+    $safeExpr = new RawFilter(new YourSafeNode());
+
 .. _callback: https://www.php.net/manual/en/function.is-callable.php

src/Node/Expression/ConstantExpression.php

@@ -14,6 +14,9 @@ namespace Twig\Node\Expression;
 
 use Twig\Compiler;
 
+/**
+ * @final
+ */
 class ConstantExpression extends AbstractExpression
 {
     public function __construct($value, int $lineno)