From bfbe89e3a3dbef475f8813cdfa3dc4c33f86c3b5 Mon Sep 17 00:00:00 2001
From: "Alexander M. Turek" <alexander.turek@sensiolabs.de>
Date: Mon, 21 Sep 2026 18:10:25 +0200
Subject: [PATCH] Allow to call TemplateWrapper::unwrap() without arguments

---
 src/TemplateWrapper.php       |  6 ++++--
 tests/TemplateWrapperTest.php | 18 ++++++++++++++++++
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/TemplateWrapper.php b/src/TemplateWrapper.php
index c900d74fe..e08fd2cd8 100644
--- a/src/TemplateWrapper.php
+++ b/src/TemplateWrapper.php
@@ -121,9 +121,11 @@ final class TemplateWrapper
     /**
      * @internal
      */
-    public function unwrap(Environment $env): Template
+    public function unwrap(?Environment $env = null): Template
     {
-        if (!$this->isOwnedBy($env)) {
+        if (null === $env) {
+            trigger_deprecation('twig/twig', '3.29', 'Calling "%s()" without arguments is deprecated, pass the Twig environment instead.', __METHOD__);
+        } elseif (!$this->isOwnedBy($env)) {
             throw new RuntimeError(\sprintf('A "%s" can only be used with the "%s" that created it.', self::class, Environment::class));
         }
 
diff --git a/tests/TemplateWrapperTest.php b/tests/TemplateWrapperTest.php
index 38cf7a51f..6b1d2d732 100644
--- a/tests/TemplateWrapperTest.php
+++ b/tests/TemplateWrapperTest.php
@@ -21,7 +21,9 @@ namespace Twig\Tests;
  */
 
 use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\TestCase;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Twig\Environment;
 use Twig\Error\LoaderError;
 use Twig\Error\RuntimeError;
@@ -31,6 +33,8 @@ use Twig\TwigFunction;
 
 class TemplateWrapperTest extends TestCase
 {
+    use ExpectDeprecationTrait;
+
     public function testUnwrapChecksTheEnvironment(): void
     {
         $twig = new Environment(new ArrayLoader(['index' => 'content']));
@@ -43,6 +47,20 @@ class TemplateWrapperTest extends TestCase
         $wrapper->unwrap(new Environment(new ArrayLoader()));
     }
 
+    /**
+     * @group legacy
+     */
+    #[Group('legacy')]
+    public function testUnwrapCanBeCalledWithoutArguments(): void
+    {
+        $twig = new Environment(new ArrayLoader(['index' => 'content']));
+        $wrapper = $twig->load('index');
+
+        $this->expectDeprecation('Since twig/twig 3.29: Calling "Twig\TemplateWrapper::unwrap()" without arguments is deprecated, pass the Twig environment instead.');
+
+        $this->assertInstanceOf(Template::class, $wrapper->unwrap());
+    }
+
     public function testGetDefaultEscapeStrategy(): void
     {
         $twig = new Environment(new ArrayLoader(['index.js.twig' => 'content']), ['autoescape' => 'name']);