Deprecate returning null from TokenParserInterface::parse()

CHANGELOG

@@ -2,6 +2,7 @@
 
  * Add support for integers in methods of `Twig\Node\Node` that take a Node name
  * Deprecate not passing a `BodyNode` instance as the body of a `ModuleNode` or `MacroNode` constructor
+ * Deprecate returning "null" from "TokenParserInterface::parse()".
  * Deprecate `OptimizerNodeVisitor::OPTIMIZE_TEXT_NODES`
  * Fix performance regression when `use_yield` is `false` (which is the default)
  * Improve compatibility when `use_yield` is `false` (as extensions still using `echo` will work as is)

doc/deprecated.rst

@@ -43,6 +43,9 @@ Nodes
 * Not passing a ``BodyNode`` instance as the body of a ``ModuleNode`` or
   ``MacroNode`` constructor is deprecated as of Twig 3.12.
 
+* Returning ``null`` from ``TokenParserInterface::parse()`` is deprecated as of
+  Twig 3.12 (as forbidden by the interface).
+
 * The second argument of the
   ``Twig\Node\Expression\CallExpression::compileArguments()`` method is
   deprecated.

src/Parser.php

@@ -173,9 +173,10 @@ class Parser
 
                     $subparser->setParser($this);
                     $node = $subparser->parse($token);
-                    if (null !== $node) {
-                        $rv[] = $node;
+                    if (!$node) {
+                        trigger_deprecation('twig/twig', '3.12', 'Returning "null" from "%s" is deprecated and forbidden by "TokenParserInterface".', $subparser::class);
                     }
+                    $rv[] = $node;
                     break;
 
                 default: