From 7c789b377ba8c618506a1c08fffec96658823e1f Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien@potencier.org>
Date: Sat, 23 Nov 2024 14:58:29 +0100
Subject: [PATCH] Deprecate not passing a Source to TokenStream

---
 CHANGELOG                 |  2 +-
 doc/deprecated.rst        |  6 ++++++
 src/TokenStream.php       | 11 +++++------
 tests/ParserTest.php      | 10 +++++-----
 tests/TokenStreamTest.php |  7 ++++---
 5 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index 4fd66a68605..f9c68374e90 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,6 +1,6 @@
 # 3.16.0 (2024-XX-XX)
 
- * n/a
+ * Deprecate not passing a `Source` instance to `TokenStream`
 
 # 3.15.0 (2024-11-17)
  
diff --git a/doc/deprecated.rst b/doc/deprecated.rst
index b16342c9fe6..3c7a42cbd8b 100644
--- a/doc/deprecated.rst
+++ b/doc/deprecated.rst
@@ -216,6 +216,12 @@ Parser
 * Passing ``null`` to ``Twig\Parser::setParent()`` is deprecated as of Twig
   3.12.
 
+Lexer
+-----
+
+* Not passing a ``Source`` instance to ``Twig\Lexer`` constructor is deprecated
+  as of Twig 3.16.
+
 Templates
 ---------
 
diff --git a/src/TokenStream.php b/src/TokenStream.php
index c91701bfe12..35aa9714fc7 100644
--- a/src/TokenStream.php
+++ b/src/TokenStream.php
@@ -27,7 +27,11 @@ public function __construct(
         private array $tokens,
         private ?Source $source = null,
     ) {
-        $this->source = $source ?: new Source('', '');
+        if (null === $this->source) {
+            trigger_deprecation('twig/twig', '3.16', \sprintf('Not passing a "%s" object to "%s" constructor is deprecated.', Source::class, __CLASS__));
+
+            $this->source = new Source('', '');
+        }
     }
 
     public function __toString()
@@ -117,11 +121,6 @@ public function getCurrent(): Token
         return $this->tokens[$this->current];
     }
 
-    /**
-     * Gets the source associated with this stream.
-     *
-     * @internal
-     */
     public function getSourceContext(): Source
     {
         return $this->source;
diff --git a/tests/ParserTest.php b/tests/ParserTest.php
index d1d23bb1b48..1b222d0de40 100644
--- a/tests/ParserTest.php
+++ b/tests/ParserTest.php
@@ -36,7 +36,7 @@ public function testUnknownTag()
             new Token(Token::NAME_TYPE, 'foo', 1),
             new Token(Token::BLOCK_END_TYPE, '', 1),
             new Token(Token::EOF_TYPE, '', 1),
-        ]);
+        ], new Source('', ''));
         $parser = new Parser(new Environment(new ArrayLoader()));
 
         $this->expectException(SyntaxError::class);
@@ -52,7 +52,7 @@ public function testUnknownTagWithoutSuggestions()
             new Token(Token::NAME_TYPE, 'foobar', 1),
             new Token(Token::BLOCK_END_TYPE, '', 1),
             new Token(Token::EOF_TYPE, '', 1),
-        ]);
+        ], new Source('', ''));
         $parser = new Parser(new Environment(new ArrayLoader()));
 
         $this->expectException(SyntaxError::class);
@@ -153,7 +153,7 @@ public function testParseIsReentrant()
             new Token(Token::NAME_TYPE, 'foo', 1),
             new Token(Token::VAR_END_TYPE, '', 1),
             new Token(Token::EOF_TYPE, '', 1),
-        ]));
+        ], new Source('', '')));
 
         $p = new \ReflectionProperty($parser, 'parent');
         $p->setAccessible(true);
@@ -208,7 +208,7 @@ protected function getParser()
 
         $p = new \ReflectionProperty($parser, 'stream');
         $p->setAccessible(true);
-        $p->setValue($parser, new TokenStream([]));
+        $p->setValue($parser, new TokenStream([], new Source('', '')));
 
         return $parser;
     }
@@ -225,7 +225,7 @@ public function parse(Token $token): Node
             new Token(Token::STRING_TYPE, 'base', 1),
             new Token(Token::BLOCK_END_TYPE, '', 1),
             new Token(Token::EOF_TYPE, '', 1),
-        ]));
+        ], new Source('', '')));
 
         $this->parser->getStream()->expect(Token::BLOCK_END_TYPE);
 
diff --git a/tests/TokenStreamTest.php b/tests/TokenStreamTest.php
index 8f86ac87a7b..a794bc0a43c 100644
--- a/tests/TokenStreamTest.php
+++ b/tests/TokenStreamTest.php
@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Twig\Error\SyntaxError;
+use Twig\Source;
 use Twig\Token;
 use Twig\TokenStream;
 
@@ -36,7 +37,7 @@ protected function setUp(): void
 
     public function testNext()
     {
-        $stream = new TokenStream(self::$tokens);
+        $stream = new TokenStream(self::$tokens, new Source('', ''));
         $repr = [];
         while (!$stream->isEOF()) {
             $token = $stream->next();
@@ -50,7 +51,7 @@ public function testEndOfTemplateNext()
     {
         $stream = new TokenStream([
             new Token(Token::BLOCK_START_TYPE, 1, 1),
-        ]);
+        ], new Source('', ''));
 
         $this->expectException(SyntaxError::class);
         $this->expectExceptionMessage('Unexpected end of template');
@@ -64,7 +65,7 @@ public function testEndOfTemplateLook()
     {
         $stream = new TokenStream([
             new Token(Token::BLOCK_START_TYPE, 1, 1),
-        ]);
+        ], new Source('', ''));
 
         $this->expectException(SyntaxError::class);
         $this->expectExceptionMessage('Unexpected end of template');