Allow SubExpressions to be PathExpression roots

This was a feature added in v2.1.0 of the Handlebars.js parser.

Author: theodorejb

composer.json

@@ -19,7 +19,7 @@
     ],
     "require": {
         "php": ">=8.2",
-        "devtheorem/php-handlebars-parser": "^1.1.0"
+        "devtheorem/php-handlebars-parser": "^1.1.1"
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.94",

composer.lock

@@ -534,6 +534,11 @@ private function MustacheStatement(MustacheStatement $mustache): string
             return self::getRuntimeFunc($fn, self::getRuntimeFunc('dv', $varPath));
         }
 
+        // SubExpression path: {{(path args)}} — compile and render the sub-expression result
+        if ($path instanceof SubExpression) {
+            return self::getRuntimeFunc($fn, $this->SubExpression($path));
+        }
+
         // Literal path — treat as named context lookup or helper call
         $literalKey = $this->getLiteralKeyName($path);
 
@@ -574,6 +579,12 @@ private function SubExpression(SubExpression $expression): string
         };
 
         if ($helperName === null) {
+            // Dynamic callable: path rooted at a sub-expression, e.g. ((helper).prop args)
+            if ($path instanceof PathExpression) {
+                $varPath = $this->PathExpression($path);
+                $args = array_map(fn($p) => $this->compileExpression($p), $expression->params);
+                return self::getRuntimeFunc('dv', implode(', ', [$varPath, ...$args]));
+            }
             throw new \Exception('Sub-expression must be a helper call');
         }
 
@@ -586,10 +597,16 @@ private function PathExpression(PathExpression $expression): string
         $depth = $expression->depth;
         $parts = $expression->parts;
 
-        $base = $this->buildBasePath($data, $depth);
-
-        // Filter out SubExpression parts for string-only operations
-        $stringParts = self::stringPartsOf($parts);
+        // When the path head is a SubExpression (e.g. (helper).foo.bar), compile the
+        // 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) . ')';
+            $stringParts = $expression->tail;
+        } else {
+            $base = $this->buildBasePath($data, $depth);
+            $stringParts = self::stringPartsOf($parts);
+        }
 
         // `this` with no parts or empty parts
         if (($expression->this_ && !$parts) || !$stringParts) {
@@ -603,8 +620,8 @@ private function PathExpression(PathExpression $expression): string
             return "isset(\$cx->partials['@partial-block' . \$cx->partialId]) ? true : null";
         }
 
-        // Check block params (depth-0, non-data, non-scoped paths only)
-        if (!$data && $depth === 0 && !self::scopedId($expression)) {
+        // Check block params (depth-0, non-data, non-scoped paths only, not SubExpression-headed)
+        if (!$hasSubExprHead && !$data && $depth === 0 && !self::scopedId($expression)) {
             $bp = $this->lookupBlockParam($stringParts[0]);
             if ($bp !== null) {
                 [$bpDepth, $bpIndex] = $bp;
@@ -631,7 +648,7 @@ private function PathExpression(PathExpression $expression): string
             if ($depth > 0) {
                 $checks[] = "isset($base)";
             }
-            if ($p !== '' && $depth === 0) {
+            if ($p !== '' && $depth === 0 && !$hasSubExprHead) {
                 $checks[] = "isset($base$p)";
             }
             $baseP = "$base$p";

src/Compiler.php

@@ -96,6 +96,7 @@ public function testRuntimePartials(): void
     #[DataProvider("dataClosuresProvider")]
     #[DataProvider("missingDataProvider")]
     #[DataProvider("syntaxProvider")]
+    #[DataProvider("subexpressionPathProvider")]
     public function testIssues(string $template, string $expected, string $desc = '', mixed $data = null, ?Options $options = null, array $helpers = []): void
     {
         $templateSpec = Handlebars::precompile($template, $options ?? new Options());
@@ -2123,4 +2124,45 @@ public static function syntaxProvider(): array
             ],
         ];
     }
+
+    /** @return list<RegIssue> */
+    public static function subexpressionPathProvider(): array
+    {
+        return [
+            [
+                'desc' => 'sub-expression as path head: standalone mustache',
+                'template' => '{{(my-helper foo).bar}}',
+                'data' => ['foo' => 'val'],
+                'helpers' => ['my-helper' => fn($arg) => ['bar' => "got:$arg"]],
+                'expected' => 'got:val',
+            ],
+            [
+                'desc' => 'sub-expression as path head: callable',
+                'template' => '{{((my-helper foo).bar baz)}}',
+                'data' => ['foo' => 'x', 'baz' => 'y'],
+                'helpers' => ['my-helper' => fn($arg) => ['bar' => fn($x) => "called:$x"]],
+                'expected' => 'called:y',
+            ],
+            [
+                'desc' => 'sub-expression as path head: argument',
+                'template' => '{{(foo (my-helper bar).baz)}}',
+                'data' => ['bar' => 'hello'],
+                'helpers' => [
+                    'my-helper' => fn($arg) => ['baz' => strtoupper($arg)],
+                    'foo' => fn($val) => "foo:$val",
+                ],
+                'expected' => 'foo:HELLO',
+            ],
+            [
+                'desc' => 'sub-expression as path head: named argument',
+                'template' => '{{(foo bar=(my-helper baz).qux)}}',
+                'data' => ['baz' => 'world'],
+                'helpers' => [
+                    'my-helper' => fn($arg) => ['qux' => strtoupper($arg)],
+                    'foo' => fn(HelperOptions $options) => $options->hash['bar'],
+                ],
+                'expected' => 'WORLD',
+            ],
+        ];
+    }
 }