Test hoisting block program closures

Author: theodorejb

src/Compiler.php

@@ -37,6 +37,16 @@ final class Compiler
      */
     private array $blockParamValues = [];
 
+    /**
+     * Hoisted block program closures: varName => closure string.
+     * Populated during main-template compilation; emitted before the render closure in composePHPRender
+     * so they are created once per template() call and reused across all render calls.
+     * Only populated when $isHoistingEnabled is true (main compiler instance, not partial compilers).
+     * @var array<string, string>
+     */
+    private array $hoistedPrograms = [];
+    private int $hoistedProgramIdx = 0;
+
     /**
      * Stack of booleans, one per active compileProgram() call.
      * Each entry is set to true if that invocation directly emitted a $blockParams reference.
@@ -58,8 +68,13 @@ final class Compiler
      */
     private bool $compilingHelperArgs = false;
 
+    /**
+     * @param bool $isHoistingEnabled Only true for the main-template Compiler. Partial compilers use the default
+     * so their block programs remain inline (partial closures are recreated per render call anyway).
+     */
     public function __construct(
         private readonly Parser $parser,
+        private readonly bool $isHoistingEnabled = false,
     ) {}
 
     public function compile(Program $program, Context $context): string
@@ -68,6 +83,8 @@ public function compile(Program $program, Context $context): string
         $this->blockParamValues = [];
         $this->bpRefStack = [];
         $this->lastCompileProgramHadDirectBpRef = false;
+        $this->hoistedPrograms = [];
+        $this->hoistedProgramIdx = 0;
         return $this->compileProgram($program);
     }
 
@@ -79,8 +96,15 @@ public function compile(Program $program, Context $context): string
     public function composePHPRender(string $code): string
     {
         $partials = implode(",\n", $this->context->partialCode);
-        $closure = self::templateClosure($code, $partials, "\n \$in = &\$cx->data['root'];");
-        return "use " . Runtime::class . " as LR;\nreturn $closure;";
+        $useVars = $this->hoistedPrograms ? implode(', ', array_keys($this->hoistedPrograms)) : '';
+        $closure = self::templateClosure($code, $partials, "\n \$in = &\$cx->data['root'];", $useVars);
+
+        $assignments = '';
+        foreach ($this->hoistedPrograms as $var => $closureStr) {
+            $assignments .= "$var = $closureStr;\n";
+        }
+
+        return "use " . Runtime::class . " as LR;\n{$assignments}return $closure;";
     }
 
     /**
@@ -257,8 +281,14 @@ private function outerBlockParamsExpr(): string
 
     /**
      * Compile a block program, pushing/popping its block params around the compilation.
-     * Returns a PHP closure string: the signature varies based on whether the program declares or
-     * inherits block params, and a $sc preamble is added when depths are accessed multiple times.
+     * Returns either a hoisted variable reference (e.g. '$p0') or an inline closure string.
+     *
+     * Closures that do not capture any runtime variable ($declaresBp receive $blockParams as a
+     * parameter; default programs have no block-param dependency) are hoisted to eval-scope
+     * variables so they are created once at template() time and reused across render calls.
+     *
+     * The one non-hoistable case is $inheritsBp && !$declaresBp: the closure must capture
+     * $blockParams from its enclosing runtime scope via use(), so it must stay inline.
      */
     private function compileProgramWithBlockParams(Program $program): string
     {
@@ -283,6 +313,26 @@ private function compileProgramWithBlockParams(Program $program): string
             $inheritsBp => "function(\$cx, \$in) use (\$blockParams)",
             default => "function(\$cx, \$in)",
         };
+        // Hoist closures that capture no runtime variable. The use($blockParams) case
+        // ($inheritsBp && !$declaresBp) must remain inline; all others are safe to hoist.
+        if ($this->isHoistingEnabled && !($inheritsBp && !$declaresBp)) {
+            $varName = '$p' . $this->hoistedProgramIdx++;
+            // Inner programs compile before outer ones (depth-first), so any $pN referenced in
+            // this body was already assigned a lower index and will be emitted first. Add a
+            // use() clause so the hoisted closure can access those sibling variables.
+            preg_match_all('/\$p\d+/', $preamble . $body, $matches);
+            $refs = array_unique($matches[0]);
+            $useClause = $refs ? ' use (' . implode(', ', $refs) . ')' : '';
+            $this->hoistedPrograms[$varName] = "$sig$useClause {{$preamble}return $body;}";
+            return $varName;
+        }
+
+        if ($inheritsBp && !$declaresBp) {
+            // Non-hoistable: use($blockParams) captures a runtime value, so the closure must stay
+            // inline. Still extend its use() clause with any hoisted $pN it references.
+            $extendedUse = $this->extendUseVarsWithHoistedRefs('$blockParams', $preamble . $body);
+            return "function(\$cx, \$in) use ($extendedUse) {{$preamble}return $body;}";
+        }
         return "$sig {{$preamble}return $body;}";
     }
 
@@ -402,7 +452,8 @@ private function DecoratorBlock(BlockStatement $block): string
         $this->context->usedPartial[$partialName] = '';
 
         // Capture $blockParams if we're inside a block-param scope so the inline partial body can access them.
-        $useVars = $this->blockParamsUseVars();
+        // Also capture any hoisted $pN programs referenced in the body.
+        $useVars = $this->extendUseVarsWithHoistedRefs($this->blockParamsUseVars(), $body);
         $escapedName = self::quote($partialName);
         return self::getRuntimeFunc('in', "\$cx, $escapedName, " . self::templateClosure($body, useVars: $useVars));
     }
@@ -480,7 +531,8 @@ private function PartialBlockStatement(PartialBlockStatement $statement): string
         $vars = $this->compilePartialParams($statement->params, $statement->hash);
 
         // Capture $blockParams if we're inside a block-param scope so the partial block body can access them.
-        $useVars = $this->blockParamsUseVars();
+        // Also capture any hoisted $pN programs referenced in the body.
+        $useVars = $this->extendUseVarsWithHoistedRefs($this->blockParamsUseVars(), $body);
         $bodyClosure = self::templateClosure($body, useVars: $useVars);
 
         if ($partialName !== null && !$found) {
@@ -924,6 +976,24 @@ private function throwKnownHelpersOnly(string $helperName): never
         throw new \Exception("You specified knownHelpersOnly, but used the unknown helper $helperName");
     }
 
+    /**
+     * Extends $useVars with any $pN hoisted program references found in $code.
+     * Called before templateClosure() and for the non-hoistable use($blockParams) closure case,
+     * so that all closures can see the hoisted program variables they reference.
+     */
+    private function extendUseVarsWithHoistedRefs(string $useVars, string $code): string
+    {
+        if (!$this->hoistedPrograms) {
+            return $useVars;
+        }
+        preg_match_all('/\$p\d+/', $code, $matches);
+        $refs = array_unique($matches[0]);
+        if (!$refs) {
+            return $useVars;
+        }
+        return $useVars ? $useVars . ', ' . implode(', ', $refs) : implode(', ', $refs);
+    }
+
     /**
      * Build an hbch (known) or dynhbch (unknown) inline helper call string.
      * @param Expression[] $params

src/Handlebars.php

@@ -30,7 +30,7 @@ public static function compile(string $template, Options $options = new Options(
     public static function precompile(string $template, Options $options = new Options()): string
     {
         self::$parser ??= (new ParserFactory())->create();
-        self::$compiler ??= new Compiler(self::$parser);
+        self::$compiler ??= new Compiler(self::$parser, isHoistingEnabled: true);
 
         $context = new Context($options);
         $program = self::$parser->parse($template, $options->ignoreStandalone);