Remove usage of ob_* functions in favor of yielding

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ permissions:
 
 jobs:
     tests:
-        name: "PHP ${{ matrix.php-version }}"
+        name: "PHP ${{ matrix.php-version }} (yield: ${{ matrix.use_yield }})"
 
         runs-on: 'ubuntu-latest'
 
@@ -31,6 +31,7 @@ jobs:
                     - '8.2'
                     - '8.3'
                 experimental: [false]
+                use_yield: [true, false]
 
         steps:
             - name: "Checkout code"
@@ -48,6 +49,11 @@ jobs:
 
             - run: composer install
 
+            - name: "Switch use_yield to true"
+              if: ${{ matrix.use_yield }}
+              run: |
+                  sed -i -e "s/'use_yield' => false/'use_yield' => true/" src/Environment.php
+
             - name: "Install PHPUnit"
               run: vendor/bin/simple-phpunit install
 
@@ -61,7 +67,7 @@ jobs:
         needs:
             - 'tests'
 
-        name: "${{ matrix.extension }} with PHP ${{ matrix.php-version }}"
+        name: "${{ matrix.extension }} PHP ${{ matrix.php-version }} (yield: ${{ matrix.use_yield }})"
 
         runs-on: 'ubuntu-latest'
 
@@ -78,15 +84,16 @@ jobs:
                     - '8.2'
                     - '8.3'
                 extension:
-                    - 'extra/cache-extra'
-                    - 'extra/cssinliner-extra'
-                    - 'extra/html-extra'
-                    - 'extra/inky-extra'
-                    - 'extra/intl-extra'
-                    - 'extra/markdown-extra'
-                    - 'extra/string-extra'
-                    - 'extra/twig-extra-bundle'
+                    - 'cache-extra'
+                    - 'cssinliner-extra'
+                    - 'html-extra'
+                    - 'inky-extra'
+                    - 'intl-extra'
+                    - 'markdown-extra'
+                    - 'string-extra'
+                    - 'twig-extra-bundle'
                 experimental: [false]
+                use_yield: [true, false]
 
         steps:
             - name: "Checkout code"
@@ -111,11 +118,16 @@ jobs:
               run: vendor/bin/simple-phpunit --version
 
             - name: "Composer install"
-              working-directory: ${{ matrix.extension}}
+              working-directory: extra/${{ matrix.extension }}
               run: composer install
 
+            - name: "Switch use_yield to true"
+              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"
-              working-directory: ${{ matrix.extension}}
+              working-directory: extra/${{ matrix.extension }}
               run: ../../vendor/bin/simple-phpunit
 
     integration-tests:

src/Environment.php

@@ -22,6 +22,7 @@
 use Twig\Extension\EscaperExtension;
 use Twig\Extension\ExtensionInterface;
 use Twig\Extension\OptimizerExtension;
+use Twig\Extension\YieldingExtension;
 use Twig\Loader\ArrayLoader;
 use Twig\Loader\ChainLoader;
 use Twig\Loader\LoaderInterface;
@@ -66,6 +67,7 @@ class Environment
     private $runtimeLoaders = [];
     private $runtimes = [];
     private $optionsHash;
+    private $useYield;
 
     /**
      * Constructor.
@@ -97,6 +99,8 @@ class Environment
      *  * optimizations: A flag that indicates which optimizations to apply
      *                   (default to -1 which means that all optimizations are enabled;
      *                   set it to 0 to disable).
+     *
+     *  * use_yield: Enable the Twig 4 mode where template are using yield instead of echo
      */
     public function __construct(LoaderInterface $loader, $options = [])
     {
@@ -110,8 +114,12 @@ public function __construct(LoaderInterface $loader, $options = [])
             'cache' => false,
             'auto_reload' => null,
             'optimizations' => -1,
+            'use_yield' => false,
         ], $options);
 
+        $this->useYield = (bool) $options['use_yield'];
+        // FIXME: deprecation if use_yield is false
+
         $this->debug = (bool) $options['debug'];
         $this->setCharset($options['charset'] ?? 'UTF-8');
         $this->autoReload = null === $options['auto_reload'] ? $this->debug : (bool) $options['auto_reload'];
@@ -122,6 +130,15 @@ public function __construct(LoaderInterface $loader, $options = [])
         $this->addExtension(new CoreExtension());
         $this->addExtension(new EscaperExtension($options['autoescape']));
         $this->addExtension(new OptimizerExtension($options['optimizations']));
+        $this->addExtension(new YieldingExtension($options['use_yield']));
+    }
+
+    /**
+     * @internal
+     */
+    public function useYield(): bool
+    {
+        return $this->useYield;
     }
 
     /**

src/Extension/YieldingExtension.php

@@ -0,0 +1,29 @@
+<?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\YieldingNodeVisitor;
+
+class YieldingExtension extends AbstractExtension
+{
+    private $yielding;
+
+    public function __construct(bool $yielding)
+    {
+        $this->yielding = $yielding;
+    }
+
+    public function getNodeVisitors(): array
+    {
+        return [new YieldingNodeVisitor($this->yielding)];
+    }
+}

src/Node/BlockNode.php

@@ -37,6 +37,14 @@ 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
             ->outdent()
             ->write("}\n\n")
         ;

src/Node/BlockReferenceNode.php

@@ -28,9 +28,16 @@ public function __construct(string $name, int $lineno, string $tag = null)
 
     public function compile(Compiler $compiler): void
     {
-        $compiler
-            ->addDebugInfo($this)
-            ->write(sprintf("\$this->displayBlock('%s', \$context, \$blocks);\n", $this->getAttribute('name')))
-        ;
+        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')))
+            ;
+        }
     }
 }

src/Node/CaptureNode.php

@@ -27,6 +27,31 @@ public function __construct(Node $body, int $lineno, string $tag = null)
 
     public function compile(Compiler $compiler): void
     {
+        if ($compiler->getEnvironment()->useYield()) {
+            if ($this->getAttribute('raw')) {
+                $compiler->raw("implode('', iterator_to_array(");
+            } else {
+                $compiler->raw("('' === \$tmp = implode('', iterator_to_array(");
+            }
+            if ($this->getAttribute('with_blocks')) {
+                $compiler->raw("(function () use (&\$context, \$macros, \$blocks) {\n");
+            } else {
+                $compiler->raw("(function () use (&\$context, \$macros) {\n");
+            }
+            $compiler
+                ->indent()
+                ->subcompile($this->getNode('body'))
+                ->outdent()
+                ->write("})() ?? new \EmptyIterator()))")
+            ;
+            if (!$this->getAttribute('raw')) {
+                $compiler->raw(") ? '' : new Markup(\$tmp, \$this->env->getCharset())");
+            }
+            $compiler->raw(";");
+
+            return;
+        }
+
         if ($this->getAttribute('with_blocks')) {
             $compiler->raw("(function () use (&\$context, \$macros, \$blocks) {\n");
         } else {

src/Node/Expression/BlockReferenceExpression.php

@@ -40,9 +40,19 @@ public function compile(Compiler $compiler): void
             if ($this->getAttribute('output')) {
                 $compiler->addDebugInfo($this);
 
-                $this
-                    ->compileTemplateCall($compiler, 'displayBlock')
-                    ->raw(";\n");
+                if ($compiler->getEnvironment()->useYield()) {
+                    $compiler->write('yield from ');
+                }
+
+                if ($compiler->getEnvironment()->useYield()) {
+                    $this
+                        ->compileTemplateCall($compiler, 'yieldBlock')
+                        ->raw(";\n");
+                } else {
+                    $this
+                        ->compileTemplateCall($compiler, 'displayBlock')
+                        ->raw(";\n");
+                }
             } else {
                 $this->compileTemplateCall($compiler, 'renderBlock');
             }
@@ -65,6 +75,10 @@ private function compileTemplateCall(Compiler $compiler, string $method): Compil
             ;
         }
 
+        if ($compiler->getEnvironment()->useYield()) {
+            $compiler->raw('->unwrap()');
+        }
+
         $compiler->raw(sprintf('->%s', $method));
 
         return $this->compileBlockArguments($compiler);

src/Node/Expression/InlinePrint.php

@@ -26,10 +26,17 @@ public function __construct(Node $node, int $lineno)
 
     public function compile(Compiler $compiler): void
     {
-        $compiler
-            ->raw('print (')
-            ->subcompile($this->getNode('node'))
-            ->raw(')')
-        ;
+        if ($compiler->getEnvironment()->useYield()) {
+            $compiler
+                ->raw('yield ')
+                ->subcompile($this->getNode('node'))
+            ;
+        } else {
+            $compiler
+                ->raw('print(')
+                ->subcompile($this->getNode('node'))
+                ->raw(')')
+            ;
+        }
     }
 }

src/Node/Expression/ParentExpression.php

@@ -28,19 +28,36 @@ public function __construct(string $name, int $lineno, string $tag = null)
 
     public function compile(Compiler $compiler): void
     {
-        if ($this->getAttribute('output')) {
-            $compiler
-                ->addDebugInfo($this)
-                ->write('$this->displayParentBlock(')
-                ->string($this->getAttribute('name'))
-                ->raw(", \$context, \$blocks);\n")
-            ;
+        if ($compiler->getEnvironment()->useYield()) {
+            if ($this->getAttribute('output')) {
+                $compiler
+                    ->addDebugInfo($this)
+                    ->write('yield from $this->yieldParentBlock(')
+                    ->string($this->getAttribute('name'))
+                    ->raw(", \$context, \$blocks);\n")
+                ;
+            } else {
+                $compiler
+                    ->raw('$this->renderParentBlock(')
+                    ->string($this->getAttribute('name'))
+                    ->raw(', $context, $blocks)')
+                ;
+            }
         } else {
-            $compiler
-                ->raw('$this->renderParentBlock(')
-                ->string($this->getAttribute('name'))
-                ->raw(', $context, $blocks)')
-            ;
+            if ($this->getAttribute('output')) {
+                $compiler
+                    ->addDebugInfo($this)
+                    ->write('$this->displayParentBlock(')
+                    ->string($this->getAttribute('name'))
+                    ->raw(", \$context, \$blocks);\n")
+                ;
+            } else {
+                $compiler
+                    ->raw('$this->renderParentBlock(')
+                    ->string($this->getAttribute('name'))
+                    ->raw(', $context, $blocks)')
+                ;
+            }
         }
     }
 }

src/Node/IncludeNode.php

@@ -58,17 +58,39 @@ public function compile(Compiler $compiler): void
                 ->write("}\n")
                 ->write(sprintf("if ($%s) {\n", $template))
                 ->indent()
-                ->write(sprintf('$%s->display(', $template))
             ;
+
+            if ($compiler->getEnvironment()->useYield()) {
+                $compiler
+                    ->write(sprintf('yield from $%s->unwrap()->yield(', $template))
+                ;
+            } else {
+                $compiler
+                    ->write(sprintf('$%s->display(', $template))
+                ;
+            }
+
             $this->addTemplateArguments($compiler);
             $compiler
                 ->raw(");\n")
                 ->outdent()
                 ->write("}\n")
             ;
         } else {
+            if ($compiler->getEnvironment()->useYield()) {
+                $compiler
+                    ->write('yield from ')
+                ;
+            }
+
             $this->addGetTemplate($compiler);
-            $compiler->raw('->display(');
+
+            if ($compiler->getEnvironment()->useYield()) {
+                $compiler->raw('->unwrap()->yield(');
+            } else {
+                $compiler->raw('->display(');
+            }
+
             $this->addTemplateArguments($compiler);
             $compiler->raw(");\n");
         }