Replace "use_yield" by #[YieldReady] on nodes

.github/workflows/ci.yml

@@ -14,12 +14,10 @@ permissions:
 
 jobs:
     tests:
-        name: "PHP ${{ matrix.php-version }} (yield: ${{ matrix.use_yield }})"
+        name: "PHP ${{ matrix.php-version }} (yield: ${{ matrix.use-yield }})"
 
         runs-on: 'ubuntu-latest'
 
-        continue-on-error: ${{ matrix.experimental }}
-
         strategy:
             matrix:
                 php-version:
@@ -30,8 +28,10 @@ jobs:
                     - '8.1'
                     - '8.2'
                     - '8.3'
-                experimental: [false]
-                use_yield: [true, false]
+                use-yield: [false]
+                include:
+                    - php-version: '8.2'
+                      use-yield: true
 
         steps:
             - name: "Checkout code"
@@ -50,7 +50,7 @@ jobs:
             - run: composer install
 
             - name: "Switch use_yield to true"
-              if: ${{ matrix.use_yield }}
+              if: ${{ matrix.use-yield }}
               run: |
                   sed -i -e "s/'use_yield' => false/'use_yield' => true/" src/Environment.php
 
@@ -61,13 +61,13 @@ jobs:
               run: vendor/bin/simple-phpunit --version
 
             - name: "Run tests"
-              run: SYMFONY_DEPRECATIONS_HELPER=ignoreFile=./tests/ignore-use-yield-deprecations vendor/bin/simple-phpunit
+              run: vendor/bin/simple-phpunit
 
     extension-tests:
         needs:
             - 'tests'
 
-        name: "${{ matrix.extension }} PHP ${{ matrix.php-version }} (yield: ${{ matrix.use_yield }})"
+        name: "${{ matrix.extension }} PHP ${{ matrix.php-version }} (yield: ${{ matrix.use-yield }})"
 
         runs-on: 'ubuntu-latest'
 
@@ -92,8 +92,10 @@ jobs:
                     - 'markdown-extra'
                     - 'string-extra'
                     - 'twig-extra-bundle'
-                experimental: [false]
-                use_yield: [true, false]
+                use-yield: [false]
+                include:
+                    - php-version: '8.2'
+                      use-yield: true
 
         steps:
             - name: "Checkout code"
@@ -123,13 +125,13 @@ jobs:
               run: composer install
 
             - name: "Switch use_yield to true"
-              if: ${{ matrix.use_yield }}
+              if: ${{ matrix.use-yield }}
               run: |
                   sed -i -e "s/'use_yield' => false/'use_yield' => true/" extra/${{ matrix.extension }}/vendor/twig/twig/src/Environment.php
 
             - name: "Run tests for ${{ matrix.extension}}"
               working-directory: extra/${{ matrix.extension }}
-              run: SYMFONY_DEPRECATIONS_HELPER=ignoreFile=../../tests/ignore-use-yield-deprecations ../../vendor/bin/simple-phpunit
+              run: ../../vendor/bin/simple-phpunit
 
     integration-tests:
         needs:

src/Compiler.php

@@ -27,12 +27,12 @@ class Compiler
     private $sourceOffset;
     private $sourceLine;
     private $varNameSalt = 0;
-    private $checkForOutput;
+    private $didUseEcho = false;
+    private $didUseEchoStack = [];
 
     public function __construct(Environment $env)
     {
         $this->env = $env;
-        $this->checkForOutput = $env->isDebug();
     }
 
     public function getEnvironment(): Environment
@@ -68,33 +68,33 @@ public function reset(int $indentation = 0)
     public function compile(Node $node, int $indentation = 0)
     {
         $this->reset($indentation);
-        $node->compile($this);
 
-        return $this;
+        return $this->subcompile($node);
     }
 
     /**
      * @return $this
      */
     public function subcompile(Node $node, bool $raw = true)
     {
-        if (false === $raw) {
+        if (!$raw) {
             $this->source .= str_repeat(' ', $this->indentation * 4);
         }
 
-        $node->compile($this);
+        $this->didUseEchoStack[] = $this->didUseEcho;
 
-        return $this;
-    }
+        try {
+            $this->didUseEcho = false;
+            $node->compile($this);
 
-    /**
-     * @return $this
-     */
-    public function checkForOutput(bool $checkForOutput)
-    {
-        $this->checkForOutput = $checkForOutput ? $this->env->isDebug() : false;
+            if ($this->didUseEcho) {
+                trigger_deprecation('twig/twig', '3.9', 'Using "%s" is deprecated, use "yield" instead in "%s", then flag the class with #[YieldReady].', $this->didUseEcho, \get_class($node));
+            }
 
-        return $this;
+            return $this;
+        } finally {
+            $this->didUseEcho = array_pop($this->didUseEchoStack);
+        }
     }
 
     /**
@@ -104,9 +104,7 @@ public function checkForOutput(bool $checkForOutput)
      */
     public function raw(string $string)
     {
-        if ($this->checkForOutput) {
-            $this->checkStringForOutput(trim($string));
-        }
+        $this->checkForEcho($string);
         $this->source .= $string;
 
         return $this;
@@ -120,10 +118,7 @@ public function raw(string $string)
     public function write(...$strings)
     {
         foreach ($strings as $string) {
-            if ($this->checkForOutput) {
-                $this->checkStringForOutput(trim($string));
-            }
-
+            $this->checkForEcho($string);
             $this->source .= str_repeat(' ', $this->indentation * 4).$string;
         }
 
@@ -240,12 +235,13 @@ public function getVarName(): string
         return sprintf('__internal_compile_%d', $this->varNameSalt++);
     }
 
-    private function checkStringForOutput(string $string): void
+    private function checkForEcho(string $string): void
     {
-        if (str_starts_with($string, 'echo')) {
-            trigger_deprecation('twig/twig', '3.9.0', 'Using "echo" in a "Node::compile()" method is deprecated; use a "TextNode" or "PrintNode" instead or use "yield" when "use_yield" is "true" on the environment (triggered by "%s").', $string);
-        } elseif (str_starts_with($string, 'print')) {
-            trigger_deprecation('twig/twig', '3.9.0', 'Using "print" in a "Node::compile()" method is deprecated; use a "TextNode" or "PrintNode" instead or use "yield" when "use_yield" is "true" on the environment (triggered by "%s").', $string);
+        if ($this->didUseEcho) {
+            return;
         }
+
+        $string = trim($string);
+        $this->didUseEcho = str_starts_with($string, 'echo') ? 'echo' : (str_starts_with($string, 'print(') ? 'print' : false);
     }
 }

src/Environment.php

@@ -22,6 +22,7 @@
 use Twig\Extension\EscaperExtension;
 use Twig\Extension\ExtensionInterface;
 use Twig\Extension\OptimizerExtension;
+use Twig\Extension\YieldNotReadyExtension;
 use Twig\Loader\ArrayLoader;
 use Twig\Loader\ChainLoader;
 use Twig\Loader\LoaderInterface;
@@ -100,7 +101,7 @@ class Environment
      *                   (default to -1 which means that all optimizations are enabled;
      *                   set it to 0 to disable).
      *
-     *  * use_yield: Enable a new mode where template are using "yield" instead of "echo"
+     *  * use_yield: Enable templates to exclusively use "yield" instead of "echo"
      *               (default to "false", but switch it to "true" when possible
      *               as this will be the only supported mode in Twig 4.0)
      */
@@ -120,10 +121,6 @@ public function __construct(LoaderInterface $loader, $options = [])
         ], $options);
 
         $this->useYield = (bool) $options['use_yield'];
-        if (!$this->useYield) {
-            trigger_deprecation('twig/twig', '3.9.0', 'Not setting "use_yield" to "true" is deprecated.');
-        }
-
         $this->debug = (bool) $options['debug'];
         $this->setCharset($options['charset'] ?? 'UTF-8');
         $this->autoReload = null === $options['auto_reload'] ? $this->debug : (bool) $options['auto_reload'];
@@ -133,6 +130,11 @@ public function __construct(LoaderInterface $loader, $options = [])
 
         $this->addExtension(new CoreExtension());
         $this->addExtension(new EscaperExtension($options['autoescape']));
+        if (\PHP_VERSION_ID >= 80000) {
+            $this->addExtension(new YieldNotReadyExtension($this->useYield));
+        } elseif ($this->useYield) {
+            throw new \LogicException('The "use_yield" option of Twig can only be enabled when running on PHP 8.0 or later.');
+        }
         $this->addExtension(new OptimizerExtension($options['optimizations']));
     }
 
@@ -854,7 +856,6 @@ private function updateOptionsHash(): void
             self::VERSION,
             (int) $this->debug,
             (int) $this->strictVariables,
-            $this->useYield ? '1' : '0',
         ]);
     }
 }

src/Extension/YieldNotReadyExtension.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of Twig.
+ *
+ * (c) Fabien Potencier
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Twig\Extension;
+
+use Twig\NodeVisitor\YieldNotReadyNodeVisitor;
+
+/**
+ * @internal to be removed in Twig 4
+ */
+final class YieldNotReadyExtension extends AbstractExtension
+{
+    private $useYield;
+
+    public function __construct(bool $useYield)
+    {
+        $this->useYield = $useYield;
+    }
+
+    public function getNodeVisitors(): array
+    {
+        return [new YieldNotReadyNodeVisitor($this->useYield)];
+    }
+}

src/Node/AutoEscapeNode.php

@@ -24,6 +24,7 @@
  *
  * @author Fabien Potencier <[email protected]>
  */
+#[YieldReady]
 class AutoEscapeNode extends Node
 {
     public function __construct($value, Node $body, int $lineno, string $tag = 'autoescape')

src/Node/BlockNode.php

@@ -19,6 +19,7 @@
  *
  * @author Fabien Potencier <[email protected]>
  */
+#[YieldReady]
 class BlockNode extends Node
 {
     public function __construct(string $name, Node $body, int $lineno, ?string $tag = null)
@@ -37,14 +38,7 @@ public function compile(Compiler $compiler): void
 
         $compiler
             ->subcompile($this->getNode('body'))
-        ;
-
-        if (!$this->getNode('body') instanceof NodeOutputInterface && $compiler->getEnvironment()->useYield()) {
-            // needed when body doesn't yield anything
-            $compiler->write("yield '';\n");
-        }
-
-        $compiler
+            ->write("return; yield '';\n") // needed when body doesn't yield anything
             ->outdent()
             ->write("}\n\n")
         ;

src/Node/BlockReferenceNode.php

@@ -19,6 +19,7 @@
  *
  * @author Fabien Potencier <[email protected]>
  */
+#[YieldReady]
 class BlockReferenceNode extends Node implements NodeOutputInterface
 {
     public function __construct(string $name, int $lineno, ?string $tag = null)
@@ -28,16 +29,9 @@ public function __construct(string $name, int $lineno, ?string $tag = null)
 
     public function compile(Compiler $compiler): void
     {
-        if ($compiler->getEnvironment()->useYield()) {
-            $compiler
-                ->addDebugInfo($this)
-                ->write(sprintf("yield from \$this->unwrap()->yieldBlock('%s', \$context, \$blocks);\n", $this->getAttribute('name')))
-            ;
-        } else {
-            $compiler
-                ->addDebugInfo($this)
-                ->write(sprintf("\$this->displayBlock('%s', \$context, \$blocks);\n", $this->getAttribute('name')))
-            ;
-        }
+        $compiler
+            ->addDebugInfo($this)
+            ->write(sprintf("yield from \$this->unwrap()->yieldBlock('%s', \$context, \$blocks);\n", $this->getAttribute('name')))
+        ;
     }
 }

src/Node/BodyNode.php

@@ -16,6 +16,7 @@
  *
  * @author Fabien Potencier <[email protected]>
  */
+#[YieldReady]
 class BodyNode extends Node
 {
 }