Deprecate not passing a Source to TokenStream

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)
  

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\TokenStream`` constructor is
+  deprecated as of Twig 3.16.
+
 Templates
 ---------
 

src/TokenStream.php

@@ -27,7 +27,11 @@ final class TokenStream
         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 @@ final class TokenStream
         return $this->tokens[$this->current];
     }
 
-    /**
-     * Gets the source associated with this stream.
-     *
-     * @internal
-     */
     public function getSourceContext(): Source
     {
         return $this->source;

tests/ParserTest.php

@@ -36,7 +36,7 @@ class ParserTest extends TestCase
             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 @@ class ParserTest extends TestCase
             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 @@ class ParserTest extends TestCase
             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 @@ EOF
 
         $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 @@ class TestTokenParser extends AbstractTokenParser
             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);
 

tests/TokenStreamTest.php

@@ -13,6 +13,7 @@ namespace Twig\Tests;
 
 use PHPUnit\Framework\TestCase;
 use Twig\Error\SyntaxError;
+use Twig\Source;
 use Twig\Token;
 use Twig\TokenStream;
 
@@ -36,7 +37,7 @@ class TokenStreamTest extends TestCase
 
     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 @@ class TokenStreamTest extends TestCase
     {
         $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 @@ class TokenStreamTest extends TestCase
     {
         $stream = new TokenStream([
             new Token(Token::BLOCK_START_TYPE, 1, 1),
-        ]);
+        ], new Source('', ''));
 
         $this->expectException(SyntaxError::class);
         $this->expectExceptionMessage('Unexpected end of template');