Enable dynamic partial registration in helpers

Added `hasPartial` and `registerPartial` methods to HelperOptions, which makes possible the same pattern available in Handlebars.js of checking `Handlebars.partials` and calling `Handlebars.registerPartial` inside a helper.

Also fixed `isset($options->fn)` and `isset($options->inverse)` checks to align with the existence of these methods in Handlebars.js for all block helper calls.

Closes #5
Resolves zordius/lightncandy#296

Author: theodorejb

src/Compiler.php

@@ -472,7 +472,7 @@ private function PartialBlockStatement(PartialBlockStatement $statement): string
 
         if ($partialName !== null && !$found) {
             // Register the block body as a fallback partial only if no runtime partial with this name exists yet.
-            $parts[] = "(isset(\$cx->partials[$p]) ? '' : " . self::getRuntimeFunc('in', "\$cx, $p, $bodyClosure") . ')';
+            $parts[] = "(isset(\$cx->inlinePartials[$p]) || isset(\$cx->partials[$p]) ? '' : " . self::getRuntimeFunc('in', "\$cx, $p, $bodyClosure") . ')';
         }
         $parts[] = self::getRuntimeFunc('p', "\$cx, $p, $vars, '', $bodyClosure");
         return implode('.', $parts);

src/HelperOptions.php

@@ -11,6 +11,9 @@ enum Scope
     case Use;
 }
 
+/**
+ * @phpstan-import-type Template from Handlebars
+ */
 class HelperOptions
 {
     /**
@@ -21,57 +24,76 @@ class HelperOptions
     public function __construct(
         public mixed &$scope,
         public array &$data,
+        private readonly RuntimeContext $cx,
         public readonly string $name = '',
         public readonly array $hash = [],
         public readonly int $blockParams = 0,
-        private readonly ?RuntimeContext $cx = null,
         private readonly ?Closure $cb = null,
         private readonly ?Closure $inv = null,
         private readonly array $outerBlockParams = [],
     ) {}
 
     /**
-     * Allows isset($options->fn) and isset($options->inverse) to check whether the block exists.
+     * Returns true if a partial with the given name is registered.
+     */
+    public function hasPartial(string $name): bool
+    {
+        return isset($this->cx->inlinePartials[$name]) || isset($this->cx->partials[$name]);
+    }
+
+    /**
+     * Registers a compiled partial closure under the given name for the remainder of the render.
+     * Typically used alongside hasPartial() to implement lazy partial loading.
+     * @param Template $partial
+     */
+    public function registerPartial(string $name, \Closure $partial): void
+    {
+        $this->cx->partials[$name] = $partial;
+    }
+
+    /**
+     * Supports isset($options->fn) and isset($options->inverse), both of which return true for
+     * any block helper call and false for inline helper calls (matching Handlebars.js behavior).
      */
     public function __isset(string $name): bool
     {
-        if ($name === 'fn') {
-            return $this->cb !== null;
-        } elseif ($name === 'inverse') {
-            return $this->inv !== null;
+        if ($name === 'fn' || $name === 'inverse') {
+            return $this->cb !== null || $this->inv !== null;
         }
         return false;
     }
 
     public function fn(mixed $context = Scope::Use, mixed $data = null): string
     {
-        if ($this->cx === null) {
-            throw new \Exception('fn() is not supported for inline helpers');
-        } elseif ($this->cb === null) {
+        if ($this->cb === null) {
+            if ($this->inv === null) {
+                throw new \Exception('fn() is not supported for inline helpers');
+            }
             return '';
         }
         $cx = $this->cx;
         $scope = $this->scope;
 
-        // Save partials so that any {{#* inline}} partials registered inside the block body
+        // Save inlinePartials so that any {{#* inline}} partials registered inside the block body
         // don't leak out after fn() returns. The spec requires inline partials to be
         // block-scoped. PHP copy-on-write makes this assignment cheap when no inline partials are registered.
-        $savedPartials = $cx->partials;
+        $savedInlinePartials = $cx->inlinePartials;
 
         // Skip depths push for explicit same-context pass (equivalent to HBS.js options.fn(this))
         $skipDepths = $context === $scope;
         $resolvedContext = $skipDepths ? $scope : ($context === Scope::Use ? $scope : $context);
         $ret = $this->callBlock($this->cb, $resolvedContext, !$skipDepths, $data);
 
-        $cx->partials = $savedPartials;
+        $cx->inlinePartials = $savedInlinePartials;
         return $ret;
     }
 
     public function inverse(mixed $context = null, mixed $data = null): string
     {
-        if ($this->cx === null) {
-            throw new \Exception('inverse() is not supported for inline helpers');
-        } elseif ($this->inv === null) {
+        if ($this->inv === null) {
+            if ($this->cb === null) {
+                throw new \Exception('inverse() is not supported for inline helpers');
+            }
             return '';
         }
         return $this->callBlock($this->inv, $context ?? $this->scope, $context !== null, $data);
@@ -81,7 +103,6 @@ public function inverse(mixed $context = null, mixed $data = null): string
     private function callBlock(\Closure $closure, mixed $context, bool $pushDepths, ?array $data): string
     {
         $cx = $this->cx;
-        assert($cx !== null);
         $savedFrame = null;
         $bpStack = null;
 
@@ -133,12 +154,11 @@ public function iterate(array $items): string
             return '';
         }
         $cx = $this->cx;
-        assert($cx !== null);
         $cb = $this->cb;
 
-        // Push depths and save partials once for the entire loop.
+        // Push depths and save inlinePartials once for the entire loop.
         $cx->depths[] = $this->scope;
-        $savedPartials = $cx->partials;
+        $savedInlinePartials = $cx->inlinePartials;
 
         $last = count($items) - 1;
         $ret = '';
@@ -166,7 +186,7 @@ public function iterate(array $items): string
 
         $cx->frame = $outerFrame;
         array_pop($cx->depths);
-        $cx->partials = $savedPartials;
+        $cx->inlinePartials = $savedInlinePartials;
         return $ret;
     }
 }

src/Runtime.php

@@ -181,12 +181,13 @@ public static function createContext(mixed $context, array $options, array $comp
 
         if ($parentCx !== null) {
             // Partial context: reuse the parent's already-merged helpers and partials directly.
-            // PHP copy-on-write ensures partials is only copied if in() registers a new inline partial.
+            // PHP copy-on-write ensures inlinePartials is only copied if in() registers a new inline partial.
             // Inherit the parent's current frame so @index, @key, etc. remain accessible inside partials.
             // templateClosure will update frame['root'] to reference this partial's own data['root'].
             return new RuntimeContext(
                 helpers: $parentCx->helpers,
                 partials: $parentCx->partials,
+                inlinePartials: $parentCx->inlinePartials,
                 depths: $parentCx->depths,
                 data: $root,
                 frame: $parentCx->frame,
@@ -391,7 +392,9 @@ public static function merge(mixed $a, mixed $b): mixed
      */
     public static function p(RuntimeContext $cx, string $name, mixed $context, array $hash, string $indent, ?\Closure $partialBlock = null): string
     {
-        $fn = $name === '@partial-block' ? $cx->partialBlock : ($cx->partials[$name] ?? null);
+        // inlinePartials (block-scoped {{#* inline}}) take precedence over partials (persistent),
+        // mirroring Handlebars.js which checks options.partials before env.partials.
+        $fn = $name === '@partial-block' ? $cx->partialBlock : ($cx->inlinePartials[$name] ?? $cx->partials[$name] ?? null);
         if ($fn === null) {
             throw new \Exception("The partial $name could not be found");
         }
@@ -448,7 +451,7 @@ public static function p(RuntimeContext $cx, string $name, mixed $context, array
      */
     public static function in(RuntimeContext $cx, string $name, \Closure $partial): string
     {
-        $cx->partials[$name] = $partial;
+        $cx->inlinePartials[$name] = $partial;
         return '';
     }
 
@@ -502,6 +505,7 @@ public static function hbch(RuntimeContext $cx, \Closure $helper, string $name,
             $positional[] = new HelperOptions(
                 scope: $_this,
                 data: $cx->frame,
+                cx: $cx,
                 name: $name,
                 hash: $hash,
             );
@@ -525,10 +529,10 @@ public static function hbbch(RuntimeContext $cx, \Closure $helper, string $name,
         $positional[] = new HelperOptions(
             scope: $_this,
             data: $cx->frame,
+            cx: $cx,
             name: $name,
             hash: $hash,
             blockParams: $blockParamCount,
-            cx: $cx,
             cb: $cb,
             inv: $else,
             outerBlockParams: $outerBlockParams,

src/RuntimeContext.php

@@ -9,14 +9,16 @@ final class RuntimeContext
 {
     /**
      * @param array<string, \Closure> $helpers
-     * @param array<string, \Closure> $partials
+     * @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<mixed> $depths
      * @param array<mixed> $data
      * @param array<mixed> $frame
      */
     public function __construct(
         public array $helpers = [],
         public array $partials = [],
+        public array $inlinePartials = [],
         public array $depths = [],
         public array $data = [],
         public array $frame = [],

tests/ErrorTest.php

@@ -3,6 +3,7 @@
 namespace DevTheorem\Handlebars\Test;
 
 use DevTheorem\Handlebars\Handlebars;
+use DevTheorem\Handlebars\HelperOptions;
 use DevTheorem\Handlebars\Options;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
@@ -35,7 +36,7 @@ public function testRenderingException(
             ]);
             $this->fail("Expected to throw exception: {$expected}. CODE: $php");
         } catch (\Exception $e) {
-            $this->assertEquals($expected, $e->getMessage(), $php);
+            $this->assertSame($expected, $e->getMessage(), $php);
         }
     }
 
@@ -127,6 +128,20 @@ public static function renderErrorProvider(): array
                 'options' => new Options(strict: true),
                 'expected' => '"foo" not defined',
             ],
+            [
+                'template' => '{{foo}}',
+                'helpers' => [
+                    'foo' => fn(HelperOptions $options) => $options->fn(),
+                ],
+                'expected' => 'fn() is not supported for inline helpers',
+            ],
+            [
+                'template' => '{{foo}}',
+                'helpers' => [
+                    'foo' => fn(HelperOptions $options) => $options->inverse(),
+                ],
+                'expected' => 'inverse() is not supported for inline helpers',
+            ],
             [
                 'template' => '{{foo}}',
                 'helpers' => [

tests/HandlebarsSpecTest.php

@@ -158,7 +158,7 @@ public function testSpecs(array $spec): void
             $this->fail("Should Fail: " . self::getSpecDetails($spec, $php, $helpersList) . "\n\nResult: $result");
         }
 
-        $this->assertEquals($spec['expected'], $result, self::getSpecDetails($spec, $php, $helpersList));
+        $this->assertSame($spec['expected'], $result, self::getSpecDetails($spec, $php, $helpersList));
     }
 
     /**