Switch to objects (experimental)

Author: theodorejb

php_handlebars_template.php

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="tests/bootstrap.php">
+    <testsuites>
+        <testsuite name="default">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

phpunit.xml

@@ -79,7 +79,7 @@ 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'];");
+        $closure = self::templateClosure($code, $partials, "\n \$in = &\$cx->data->root;");
         return "use " . Runtime::class . " as LR;\nreturn $closure;";
     }
 
@@ -590,7 +590,9 @@ private function PathExpression(PathExpression $expression): string
         // sub-expression as the base and use the string tail as the remaining key accesses.
         $hasSubExprHead = $expression->head instanceof SubExpression;
         if ($hasSubExprHead) {
-            $base = '(' . $this->SubExpression($expression->head) . ')';
+            // Normalize the sub-expression result so PHP array returns become ArrayContext and
+            // can be accessed via ->{'key'} property syntax.
+            $base = 'LR::normalizeContext(' . $this->SubExpression($expression->head) . ')';
             $stringParts = $expression->tail;
         } else {
             $base = $this->buildBasePath($data, $depth);
@@ -818,7 +820,7 @@ private function getSimpleHelperName(PathExpression|Literal $path): ?string
     private function buildBasePath(bool $data, int $depth): string
     {
         if ($data) {
-            return '$cx->data' . str_repeat("['_parent']", $depth);
+            return '$cx->data' . str_repeat('->_parent', $depth);
         }
         return $depth > 0 ? "\$cx->depths[count(\$cx->depths)-$depth]" : '$in';
     }
@@ -848,15 +850,15 @@ private static function buildCallChain(string $fn, string $base, array $parts, ?
     }
 
     /**
-     * Build a chained array-access string for the given path parts.
-     * e.g. ['foo', 'bar'] → "['foo']['bar']"
+     * Build a chained object-property-access string for the given path parts.
+     * e.g. ['foo', 'bar'] → "->{'foo'}->{'bar'}"
      * @param string[] $parts
      */
     private static function buildKeyAccess(array $parts): string
     {
         $n = '';
         foreach ($parts as $part) {
-            $n .= '[' . self::quote($part) . ']';
+            $n .= '->{' . self::quote($part) . '}';
         }
         return $n;
     }
@@ -908,10 +910,11 @@ private function compileModeAwareLookup(string $base, array $parts, string $orig
             return $base;
         }
         if ($this->context->options->assumeObjects || ($this->context->options->strict && $this->compilingHelperArgs)) {
-            // Use nullCheck chain for assumeObjects and helper arguments in strict mode.
-            // This mirrors HBS.js: both paths use bare nameLookup, so only a null intermediate throws
-            // (JS TypeError), while a missing key on a valid object returns null silently (JS undefined).
-            return self::buildCallChain('nullCheck', $base, $parts);
+            // Bare access without ??: a null intermediate triggers a PHP warning that the null-property
+            // handler converts to an ErrorException (PHP 8), or a native TypeError (PHP 9).
+            // This mirrors HBS.js assumeObjects: missing keys on valid objects return null silently
+            // (stdClass property access), while null intermediates throw.
+            return $base . self::buildKeyAccess($parts);
         }
         if ($this->context->options->strict) {
             return self::buildCallChain('strictLookup', $base, $parts, self::quote($original));

src/Compiler.php

@@ -46,15 +46,13 @@ public static function template(string $templateSpec): \Closure
 
     /**
      * 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(),
+     * Use this in block helpers before passing a data object 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
+    public static function createFrame(\stdClass $data): \stdClass
     {
-        $frame = $data;
-        $frame['_parent'] = $data;
+        $frame = clone $data;
+        $frame->_parent = $data;
         return $frame;
     }
 

src/Handlebars.php

@@ -17,13 +17,12 @@ enum Scope
 class HelperOptions
 {
     /**
-     * @param array<mixed> $data
      * @param array<mixed> $hash
      * @param array<mixed> $outerBlockParams outer block param stack, passed as trailing elements of the stack
      */
     public function __construct(
         public mixed &$scope,
-        public array &$data,
+        public \stdClass &$data,
         private readonly RuntimeContext $cx,
         public readonly string $name = '',
         public readonly array $hash = [],
@@ -96,18 +95,37 @@ private function invokeBlock(\Closure $closure, mixed $context, mixed $data): st
         // Skip depths push when the caller explicitly passes the current scope (equivalent to
         // HBS.js options.fn(this) / options.inverse(this)), since the scope level isn't changing.
         $pushDepths = $context !== $scope;
-        $resolvedContext = $pushDepths ? ($context === Scope::Use ? $scope : $context) : $scope;
+        $resolvedContext = $pushDepths
+            ? ($context === Scope::Use ? $scope : Runtime::normalizeContext($context))
+            : $scope;
         $outerFrame = null;
         $bpStack = null;
 
-        if (isset($data['data'])) {
+        // Accept legacy array data arg for backward compatibility.
+        if (is_array($data)) {
+            $data = (object) $data;
+        }
+
+        if (isset($data->data)) {
             $outerFrame = $cx->data;
-            $cx->data = $data['data'];
+            if (is_array($data->data)) {
+                $frame = new DataFrame();
+                foreach ($data->data as $k => $v) {
+                    $frame->$k = $v;
+                }
+                $cx->data = $frame;
+            } else {
+                $cx->data = $data->data;
+            }
         }
 
-        if (isset($data['blockParams'])) {
+        if (isset($data->blockParams)) {
             // Build block params stack: current level prepended to outer stack.
-            $bpStack = [$data['blockParams'], ...$this->outerBlockParams];
+            // Normalize each value so block param property access uses stdClass syntax.
+            $bpStack = [
+                array_map(Runtime::normalizeContext(...), $data->blockParams),
+                ...$this->outerBlockParams,
+            ];
         }
 
         if ($pushDepths) {
@@ -160,18 +178,19 @@ public function iterate(array $items): string
         // so the next iteration's assignment is an in-place mutation, not a copy.
         $bpStack = [[null, null], ...$this->outerBlockParams];
         $data = Handlebars::createFrame($outerFrame);
-        $data['first'] = true;
+        $data->first = true;
+        $cx->data = $data;
 
         foreach ($items as $index => $value) {
-            $data['key'] = $index;
-            $data['index'] = $i;
-            $data['last'] = $i === $last;
-            $cx->data = $data;
+            $data->key = $index;
+            $data->index = $i;
+            $data->last = $i === $last;
 
-            $bpStack[0][0] = $value;
+            $normalized = Runtime::normalizeContext($value);
+            $bpStack[0][0] = $normalized;
             $bpStack[0][1] = $index;
-            $ret .= $cb($cx, $value, $bpStack);
-            $data['first'] = false;
+            $ret .= $cb($cx, $normalized, $bpStack);
+            $data->first = false;
             $i++;
         }