Deprecate Twig\Sandbox\SecurityPolicy::setStrict()

CHANGELOG

@@ -1,5 +1,6 @@
 # 4.0.0 (2026-XX-XX)
 
+ * Deprecate `Twig\Sandbox\SecurityPolicy::setStrict()`, kept as a no-op for forward compatibility with 3.x and to be removed in 5.0
  * Remove the `Twig\Sandbox\SourcePolicyInterface` interface and the corresponding argument of `Twig\Extension\SandboxExtension::__construct()`
  * Enforce the `parent`, `block`, and `attribute` functions against the sandbox `allowedFunctions` allow-list
 

doc/deprecated.rst

@@ -4,3 +4,12 @@ Deprecated Features
 This document lists deprecated features in Twig 4.x. Deprecated features are
 kept for backward compatibility and removed in the next major release (a
 feature that was deprecated in Twig 4.x is removed in Twig 5.0).
+
+Sandbox
+-------
+
+* The ``Twig\Sandbox\SecurityPolicy::setStrict()`` method is deprecated as of
+  Twig 4.0 and will be removed in 5.0. The method is kept as a no-op so that
+  code written against Twig 3.x (where it opted-in to the 4.0 sandbox
+  behavior) keeps running unmodified on 4.x. Drop the call once you no
+  longer need to support Twig 3.x.

src/Sandbox/SecurityPolicy.php

@@ -80,16 +80,16 @@ public function setAllowedFunctions(array $functions): void
     }
 
     /**
-     * Kept as a no-op for forward compatibility with 3.x code bases.
+     * No-op kept for forward compatibility with 3.x: on 3.x this method opts-in
+     * to the 4.0 sandbox behavior for the ``extends``/``use`` tags and the
+     * ``parent``/``block``/``attribute`` functions; on 4.x that behavior is the
+     * default, so calling this method has no effect.
      *
-     * In 3.x, this method toggled an opt-in to the 4.0 sandbox behavior for the
-     * ``extends`` and ``use`` tags and the ``parent``, ``block``, and ``attribute``
-     * functions. In 4.0 that behavior is the default and cannot be turned off, so
-     * calling this method has no effect; it exists only to let user code run
-     * unmodified on both 3.x and 4.0.
+     * @deprecated since Twig 4.0, will be removed in 5.0
      */
     public function setStrict(bool $strict): void
     {
+        trigger_deprecation('twig/twig', '4.0', 'The "%s()" method is deprecated and will be removed in 5.0; it is a no-op on Twig 4.x.', __METHOD__);
     }
 
     public function checkSecurity($tags, $filters, $functions): void

tests/Extension/SandboxTest.php

@@ -964,13 +964,33 @@ public function testColumnFilterUnaffectedOutsideSandbox()
     }
 
     /**
-     * Kept for forward compatibility with 3.x: code calling setStrict() must keep working.
+     * `setStrict()` is kept as a no-op on 4.x so that code written against 3.x
+     * runs unmodified, but it is deprecated and triggers a deprecation notice.
      */
-    public function testSetStrictIsANoOp()
+    public function testSetStrictIsADeprecatedNoOp()
     {
         $policy = new SecurityPolicy([], [], [], [], []);
-        $policy->setStrict(true);
-        $policy->setStrict(false);
+
+        $deprecations = [];
+        try {
+            set_error_handler(static function ($type, $msg) use (&$deprecations) {
+                if (\E_USER_DEPRECATED === $type) {
+                    $deprecations[] = $msg;
+                }
+
+                return true;
+            });
+
+            $policy->setStrict(true);
+            $policy->setStrict(false);
+        } finally {
+            restore_error_handler();
+        }
+
+        $this->assertSame([
+            'Since twig/twig 4.0: The "Twig\Sandbox\SecurityPolicy::setStrict()" method is deprecated and will be removed in 5.0; it is a no-op on Twig 4.x.',
+            'Since twig/twig 4.0: The "Twig\Sandbox\SecurityPolicy::setStrict()" method is deprecated and will be removed in 5.0; it is a no-op on Twig 4.x.',
+        ], $deprecations);
 
         // 4.0 behavior is the default and unaffected by setStrict()
         $this->expectException(SecurityNotAllowedTagError::class);