Move partial resolution from compile time to runtime

theodorejb · theodorejb · commit c5bc68404684 · 2026-04-27T21:02:17.000-05:00
Compile-time partials were embedded directly into every template referencing them, causing the same partial to be recompiled and duplicated across all templates that shared it, which was inefficient and inflexible.

This commit removes the `partials` and `partialResolver` compile options, and adds a new `partialResolver` runtime option.

This allows all partials in a directory to be precompiled once, and then lazily resolved at runtime and reused across any number of templates without redundant work.
diff --git a/src/Compiler.php b/src/Compiler.php
diff --git a/src/Context.php b/src/Context.php
diff --git a/src/Handlebars.php b/src/Handlebars.php
@@ -7,13 +7,18 @@
 use DevTheorem\HandlebarsParser\ParserFactory;
 
 /**
- * @phpstan-type RenderOptions array{data?: array<mixed>, helpers?: array<string, Closure>, partials?: array<string, Closure>}
+ * @phpstan-type RenderOptions array{
+ *     data?: array<mixed>,
+ *     helpers?: array<Closure>,
+ *     partials?: array<Closure>,
+ *     partialResolver?: Closure(string): ?Closure,
+ * }
  * @phpstan-type Template Closure(mixed=, RenderOptions=): string
  */
 final class Handlebars
 {
     private static ?Parser $parser = null;
-    private static ?Compiler $compiler = null;
+    private static Compiler $compiler;
 
     /**
      * Compiles a template so it can be executed immediately.
@@ -30,12 +35,10 @@ 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();
 
-        $context = new Context($options);
         $program = self::$parser->parse($template, $options->ignoreStandalone);
-        $code = self::$compiler->compile($program, $context);
-        self::$compiler->handleDynamicPartials();
+        $code = self::$compiler->compile($program, $options);
 
         return self::$compiler->composePHPRender($code);
     }
diff --git a/src/Options.php b/src/Options.php
@@ -2,17 +2,13 @@
 
 namespace DevTheorem\Handlebars;
 
-use Closure;
-
 final readonly class Options
 {
-    /** @var array<string, bool> */
+    /** @var array<bool> */
     public array $knownHelpers;
 
     /**
-     * @param array<string, bool> $knownHelpers
-     * @param array<string, string> $partials
-     * @param null|Closure(string):(string|null) $partialResolver
+     * @param array<bool> $knownHelpers
      */
     public function __construct(
         public bool $compat = false,
@@ -24,8 +20,6 @@ public function __construct(
         public bool $preventIndent = false,
         public bool $ignoreStandalone = false,
         public bool $explicitPartialContext = false,
-        public array $partials = [],
-        public ?Closure $partialResolver = null,
     ) {
         $builtIn = ['if' => true, 'unless' => true, 'each' => true, 'with' => true, 'lookup' => true, 'log' => true];
         $this->knownHelpers = $knownHelpers ? array_replace($builtIn, $knownHelpers) : $builtIn;
diff --git a/src/Runtime.php b/src/Runtime.php
@@ -160,18 +160,17 @@ public static function lookupLength(mixed $base, bool $strict = false): mixed
     }
 
     /**
-     * Build a RuntimeContext from raw render options and compile-time partial closures.
+     * Build a RuntimeContext from raw render options.
      *
      * @param RenderOptions|array{_cx?: RuntimeContext} $options
-     * @param array<string, Closure> $compiledPartials
      */
-    public static function createContext(mixed $context, array $options, array $compiledPartials): RuntimeContext
+    public static function createContext(mixed $context, array $options): RuntimeContext
     {
         $parentCx = $options['_cx'] ?? null;
         $data = $options['data'] ?? [];
 
         if ($parentCx !== null) {
-            // Partial context: reuse the parent's already-merged helpers and partials directly.
+            // Partial context: reuse the parent's already-merged helpers, partials, and resolver directly.
             // PHP copy-on-write ensures inlinePartials is only copied if the partial registers a new {{#* inline}} partial.
             // invokePartial() always passes the caller's current data frame via options, so partials inherit @index, @key, etc.
             // Unset 'root' first to break the reference established by `$in = &$cx->data['root']` in the
@@ -181,6 +180,7 @@ public static function createContext(mixed $context, array $options, array $comp
             return new RuntimeContext(
                 helpers: $parentCx->helpers,
                 partials: $parentCx->partials,
+                partialResolver: $parentCx->partialResolver,
                 inlinePartials: $parentCx->inlinePartials,
                 depths: $parentCx->depths,
                 data: $data,
@@ -190,7 +190,8 @@ public static function createContext(mixed $context, array $options, array $comp
         $data['root'] ??= $context;
         return new RuntimeContext(
             helpers: array_replace(Runtime::defaultHelpers(), $options['helpers'] ?? []),
-            partials: array_replace($compiledPartials, $options['partials'] ?? []),
+            partials: $options['partials'] ?? [],
+            partialResolver: $options['partialResolver'] ?? null,
             data: $data,
         );
     }
@@ -387,8 +388,20 @@ private static function extend(mixed $a, mixed $b): mixed
         return $a;
     }
 
+    private static function resolveAndCachePartial(RuntimeContext $cx, string $name): ?Closure
+    {
+        if ($cx->partialResolver === null) {
+            return null;
+        }
+        $fn = ($cx->partialResolver)($name);
+        if ($fn !== null) {
+            $cx->partials[$name] = $fn;
+        }
+        return $fn;
+    }
+
     /**
-     * @param array<string, mixed> $hash named hash overrides merged into the context
+     * @param array<mixed> $hash named hash overrides merged into the context
      * @param string $indent whitespace to prepend to each line of the partial's output
      * @param mixed $callerIn When compat mode is enabled, the caller's current $in pushed onto depths so
      *                        the partial can walk up to the caller's scope (mirrors HBS.js compat depths).
@@ -402,10 +415,17 @@ public static function invokePartial(RuntimeContext $cx, ?string $name, mixed $c
             null => null,
             // inlinePartials (block-scoped {{#* inline}}) take precedence over partials (persistent),
             // mirroring Handlebars.js which checks options.partials before env.partials.
-            default => $cx->inlinePartials[$name] ?? $cx->partials[$name] ?? null,
+            // Falls back to partialResolver for lazy loading; result is cached in $cx->partials.
+            default => $cx->inlinePartials[$name] ?? $cx->partials[$name] ?? self::resolveAndCachePartial($cx, $name),
         };
 
+        $context = $hash ? self::extend($context, $hash) : $context;
+
         if ($fn === null) {
+            if ($partialBlock !== null && $name !== null) {
+                // Partial not found; render the block body as failover (mirrors HBS.js behavior).
+                return $partialBlock($context, ['data' => $cx->data, '_cx' => $cx]);
+            }
             $name ??= 'undefined'; // match HBS.js error
             throw new \Exception("The partial $name could not be found");
         }
@@ -422,7 +442,6 @@ public static function invokePartial(RuntimeContext $cx, ?string $name, mixed $c
             };
         }
 
-        $context = $hash ? self::extend($context, $hash) : $context;
         // In compat mode, push the caller's current context onto depths before creating the partial
         // context so the partial can walk up to the caller's scope. createContext() (called inside
         // the partial closure) copies $parentCx->depths, so the push must happen here, before $fn().
@@ -483,7 +502,7 @@ public static function resolveHelper(RuntimeContext $cx, string $name, mixed $ca
      * Equivalent to the invokeHelper/invokeKnownHelper opcodes in the Handlebars.js compiler.
      *
      * @param array<mixed> $positional
-     * @param array<string, mixed> $hash
+     * @param array<mixed> $hash
      */
     public static function invokeHelper(RuntimeContext $cx, Closure $helper, string $name, array $positional, array $hash, mixed &$_this): mixed
     {
@@ -517,7 +536,7 @@ public static function invokeHelper(RuntimeContext $cx, Closure $helper, string
      * Invoke a resolved block helper Closure with fn/inverse callbacks and a HelperOptions instance.
      *
      * @param array<mixed> $positional
-     * @param array<string, mixed> $hash
+     * @param array<mixed> $hash
      * @param mixed $_this current rendering context for the helper
      * @param Closure|null $cb callback function to render child context (null for inverted blocks)
      * @param Closure|null $else callback function to render child context when {{else}}
diff --git a/src/RuntimeContext.php b/src/RuntimeContext.php
@@ -10,15 +10,16 @@
 final class RuntimeContext
 {
     /**
-     * @param array<string, Closure> $helpers
-     * @param array<string, Closure> $partials compile-time and helper-registered partials (persistent)
-     * @param array<string, Closure> $inlinePartials block-scoped {{#* inline}} partials (reset on fn() return)
+     * @param array<Closure> $helpers
+     * @param array<Closure> $partials runtime-registered partials (persistent)
+     * @param array<Closure> $inlinePartials block-scoped {{#* inline}} partials (reset on fn() return)
      * @param array<mixed> $depths
      * @param array<mixed> $data
      */
     public function __construct(
         public array $helpers = [],
         public array $partials = [],
+        public ?Closure $partialResolver = null,
         public array $inlinePartials = [],
         public array $depths = [],
         public array $data = [],
diff --git a/tests/RegressionTest.php b/tests/RegressionTest.php
@@ -14,7 +14,7 @@
  * @phpstan-type RegIssue array{
  *     template: string, expected: string, data?: mixed, options?: Options,
  *     helpers?: array<Closure>, partials?: array<string>,
- *     vars?: array<mixed>,
+ *     partialResolver?: Closure, vars?: array<mixed>,
  * }
  */
 class RegressionTest extends TestCase
@@ -74,6 +74,7 @@ public function testIssues(
         ?Options $options = null,
         array $helpers = [],
         array $partials = [],
+        ?Closure $partialResolver = null,
         array $vars = [],
     ): void {
         $options ??= new Options();
@@ -82,7 +83,11 @@ public function testIssues(
         try {
             $template = Handlebars::template($templateSpec);
             $compiledPartials = array_map(fn($p) => Handlebars::compile($p, $options), $partials);
-            $result = $template($data, ['helpers' => $helpers, 'partials' => $compiledPartials, 'data' => $vars]);
+            $runtimeOptions = ['helpers' => $helpers, 'partials' => $compiledPartials, 'data' => $vars];
+            if ($partialResolver) {
+                $runtimeOptions['partialResolver'] = $partialResolver;
+            }
+            $result = $template($data, $runtimeOptions);
         } catch (\Throwable $e) {
             $this->fail("Error: {$e->getMessage()}\nPHP code:\n$templateSpec");
         }
@@ -1144,9 +1149,7 @@ public static function partialProvider(): array
 
             'partial resolver callback' => [
                 'template' => '{{>foo}} and {{>bar}}',
-                'options' => new Options(
-                    partialResolver: fn(string $name) => "PARTIAL: $name",
-                ),
+                'partialResolver' => fn(string $name) => Handlebars::compile("PARTIAL: $name"),
                 'expected' => 'PARTIAL: foo and PARTIAL: bar',
             ],
 
@@ -1216,32 +1219,16 @@ public static function nestedPartialProvider(): array
                 'expected' => 'outer+nested=~content~=nested-end+outer-end',
             ],
 
-            'LNC#292 - nested compile-time and runtime partials should render correctly' => [
+            'LNC#292 - nested partials should render correctly' => [
                 'template' => '{{#>outer}} {{#>compiledBlock}} inner compiledBlock {{/compiledBlock}} {{>normalTemplate}} {{/outer}}',
-                'options' => new Options(
-                    partials: [
-                        'outer' => 'outer+{{#>nested}}~{{>@partial-block}}~{{/nested}}+outer-end',
-                        'nested' => 'nested={{>@partial-block}}=nested-end',
-                    ],
-                ),
                 'partials' => [
+                    'outer' => 'outer+{{#>nested}}~{{>@partial-block}}~{{/nested}}+outer-end',
+                    'nested' => 'nested={{>@partial-block}}=nested-end',
                     'compiledBlock' => 'compiledBlock !!! {{>@partial-block}} !!! compiledBlock',
                     'normalTemplate' => 'normalTemplate',
                 ],
                 'expected' => 'outer+nested=~ compiledBlock !!!  inner compiledBlock  !!! compiledBlock normalTemplate ~=nested-end+outer-end',
             ],
-            'LNC#292 - nested compile-time partials should render correctly' => [
-                'template' => '{ {{#>outer}} {{#>innerBlock}} Hello {{/innerBlock}} {{>simple}} {{/outer}} }',
-                'options' => new Options(
-                    partials: [
-                        'outer' => '( {{#>nested}} « {{>@partial-block}} » {{/nested}} )',
-                        'nested' => '[ {{>@partial-block}} ]',
-                        'innerBlock' => '< {{>@partial-block}} >',
-                        'simple' => 'World!',
-                    ],
-                ),
-                'expected' => '{ ( [  «  <  Hello  > World!  »  ] ) }',
-            ],
             'LNC#292 - nested runtime partials should render correctly' => [
                 'template' => '{ {{#>outer}} {{#>innerBlock}} Hello {{/innerBlock}} {{>simple}} {{/outer}} }',
                 'partials' => [
