Implement Handlebars::createFrame utility function

Author: theodorejb

src/Handlebars.php

@@ -44,6 +44,20 @@ public static function template(string $templateSpec): \Closure
         return eval($templateSpec);
     }
 
+    /**
+     * Creates a child @data frame inheriting fields from the given frame.
+     * Use this in block helpers before passing a data array to fn() or inverse(),
+     * equivalent to Handlebars.createFrame() in Handlebars.js.
+     * @param array<mixed> $data
+     * @return array<mixed>
+     */
+    public static function createFrame(array $data): array
+    {
+        $frame = $data;
+        $frame['_parent'] = $data;
+        return $frame;
+    }
+
     /**
      * HTML escapes the passed string, making it safe for rendering as text within HTML content.
      * The output of all expressions except for triple-braced expressions are passed through this method.

src/HelperOptions.php

@@ -102,10 +102,10 @@ private function invokeBlock(\Closure $closure, mixed $context, mixed $data): st
 
         if (isset($data['data'])) {
             $savedFrame = $cx->frame;
-            // Fast path: only root in frame, no user @-data to inherit
-            $newFrame = count($savedFrame) === 1 ? $data['data'] : array_replace($savedFrame, $data['data']);
+            $newFrame = $data['data'];
+            // Reference so @root lookups work and root mutations from inside the block are visible
+            // outside it — matches HBS.js shallow-copy semantics for object properties.
             $newFrame['root'] = &$cx->data['root'];
-            $newFrame['_parent'] = $savedFrame;
             $cx->frame = $newFrame;
         }
 
@@ -169,6 +169,8 @@ public function iterate(array $items): string
         foreach ($items as $index => $value) {
             $iterData = ['key' => $index, 'index' => $i, 'first' => $i === 0, 'last' => $i === $last];
             $newFrame = $simpleFrame ? $iterData : array_replace($outerFrame, $iterData);
+            // Reference so @root lookups work and root mutations from inside the block are visible
+            // outside it — matches HBS.js shallow-copy semantics for object properties.
             $newFrame['root'] = &$cx->data['root'];
             $newFrame['_parent'] = $outerFrame;
             $cx->frame = $newFrame;

tests/HandlebarsSpecTest.php

@@ -1,31 +1,15 @@
 <?php
 
+namespace DevTheorem\Handlebars\Test;
+
 use DevTheorem\Handlebars\Handlebars;
 use DevTheorem\Handlebars\Options;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
-/**
- * Used by vendor/jbboehr/handlebars-spec/spec/data.json
- */
-class Utils
-{
-    public static function createFrame(mixed $data): mixed
-    {
-        if (is_array($data)) {
-            $r = [];
-            foreach ($data as $k => $v) {
-                $r[$k] = $v;
-            }
-            return $r;
-        }
-        return $data;
-    }
-}
-
 /**
  * @phpstan-type JsonSpec array{
- *     file: string, no: int, message: string|null, data: null|int|bool|string|array<mixed>|stdClass,
+ *     file: string, no: int, message: string|null, data: null|int|bool|string|array<mixed>|\stdClass,
  *     it: string, description: string, expected: string|null, helpers: array<mixed>,
  *     partials: array<mixed>, compileOptions: array<mixed>, template: string,
  *     exception: string|null, runtimeOptions: array<mixed>, number: string|null,
@@ -82,11 +66,7 @@ public function testSpecs(array $spec): void
             if (!isset($func['php'])) {
                 $this->markTestIncomplete("No PHP helper code provided for [{$spec['file']}#{$spec['description']}]#{$spec['no']}");
             }
-            $helper = self::patchSafeString($func['php']);
-            $helper = str_replace('$options[\'name\']', '$options->name', $helper);
-            $helper = str_replace('$options[\'data\']', '$options->data', $helper);
-            $helper = str_replace('$options[\'hash\']', '$options->hash', $helper);
-            $helper = str_replace('$arguments[count($arguments)-1][\'name\'];', '$arguments[count($arguments)-1]->name;', $helper);
+            $helper = self::patchHelperCode($func['php']);
             $helpersList .= "\n  '$name' => $helper,\n";
             eval('$helpers[\'' . $name . '\'] = ' . $helper . ';');
         }
@@ -182,7 +162,7 @@ public static function jsonSpecProvider(): array
 
         $files = glob('vendor/jbboehr/handlebars-spec/spec/*.json');
         if ($files === false) {
-            throw new Exception("Failed to read JSON spec files");
+            throw new \Exception("Failed to read JSON spec files");
         }
 
         foreach ($files as $file) {
@@ -192,7 +172,7 @@ public static function jsonSpecProvider(): array
             }
             $contents = file_get_contents($file);
             if ($contents === false) {
-                throw new Exception("Failed to read JSON spec file {$file}");
+                throw new \Exception("Failed to read JSON spec file {$file}");
             }
             $i = 0;
             $json = json_decode($contents, true);
@@ -254,10 +234,14 @@ private static function evalNestedCode(array &$data): void
         }
     }
 
-    private static function patchSafeString(string $code): string
+    private static function patchHelperCode(string $code): string
     {
-        $classname = '\\DevTheorem\\Handlebars\\SafeString';
-        return preg_replace('/ (\\\Handlebars\\\)?SafeString(\s*\(.*?\))?/', ' ' . $classname . '$2', $code)
-            ?? throw new Exception("Failed to patch SafeString in $code");
+        $code = preg_replace('/ (\\\Handlebars\\\)?SafeString(\s*\(.*?\))?/', ' \\DevTheorem\\Handlebars\\SafeString$2', $code)
+            ?? throw new \Exception("Failed to patch SafeString in $code");
+        $code = str_replace('Utils::createFrame(', '\DevTheorem\Handlebars\Handlebars::createFrame(', $code);
+        $code = str_replace('$options[\'name\']', '$options->name', $code);
+        $code = str_replace('$options[\'data\']', '$options->data', $code);
+        $code = str_replace('$options[\'hash\']', '$options->hash', $code);
+        return str_replace('$arguments[count($arguments)-1][\'name\'];', '$arguments[count($arguments)-1]->name;', $code);
     }
 }