Mark Markup as final

CHANGELOG

@@ -1,5 +1,6 @@
 # 3.28.0 (2026-XX-XX)
 
+ * Mark `Twig\Markup` as `@final`; it will be final in Twig 4.0
  * Reduce memory usage and speed up the context restoration compiled at the end of `for` loops
  * Allow calling a macro with a dynamic name via the dot operator (`macros.(name)(args)`)
  * Report the column number in syntax errors and expose it via `Error::getTemplateColumn()`

doc/deprecated.rst

@@ -5,6 +5,12 @@ This document lists deprecated features in Twig 3.x. Deprecated features are
 kept for backward compatibility and removed in the next major release (a
 feature that was deprecated in Twig 3.x is removed in Twig 4.0).
 
+Classes
+-------
+
+* The ``Twig\Markup`` class is considered final as of Twig 3.28 and will be
+  final in Twig 4.0. Use ``Twig\Markup`` directly instead of extending it.
+
 Functions
 ---------
 

src/Markup.php

@@ -14,14 +14,15 @@
 /**
  * Marks a content as safe.
  *
- * Instances of this class (and any subclass) are trusted by the Twig
- * sandbox: method calls and property accesses on a Markup instance bypass
- * the SecurityPolicy method/property allowlists. This is by design: Markup
+ * Instances of this class (and existing subclasses) are trusted by the Twig
+ * sandbox: method calls and property accesses on a Markup instance bypass the
+ * SecurityPolicy method/property allowlists. This is by design: Markup
  * represents content that has already been deemed safe to output.
  *
- * As a consequence, when extending this class, you are responsible for
- * ensuring that every method and property exposed by your subclass is
- * safe to call from a sandboxed template.
+ * This class is considered final as of Twig 3.28 and will be final in Twig
+ * 4.0.
+ *
+ * @final since Twig 3.28
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */