Share Twig call argument resolution across features

Author: fabpot

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Recognize named arguments in Twig route, template and PHP symbol calls
 - Honor named Twig translation arguments
 - Resolve YAML merge keys during configuration diagnostics
 - Treat conventional routing files as routes during configuration diagnostics

docs/features/routing.rst

@@ -19,9 +19,12 @@ Controller helpers remain recognized when an application controller inherits
 from ``AbstractController`` through one or more project base classes. Twig's
 ``path()`` and ``url()`` functions are also supported. The server avoids
 suggestions when it can't establish that a similarly named method belongs to a
-Symfony API. Static Twig route names and quoted parameter keys use Twig's string
-escape semantics. Twig parameter mappings support explicit entries such as
-``{slug: article.slug}`` and shorthand entries such as ``{year, month}``.
+Symfony API. Twig route functions recognize positional arguments and the named
+``name`` and ``parameters`` arguments. Completion expects named arguments in
+their declared order; navigation and diagnostics also recognize reordered
+named arguments. Static Twig route names and quoted parameter keys use Twig's
+string escape semantics. Twig parameter mappings support explicit entries such
+as ``{slug: article.slug}`` and shorthand entries such as ``{year, month}``.
 
 Route Name Completion
 ---------------------

docs/features/templates.rst

@@ -19,8 +19,11 @@ calls, in the ``#[Template]`` attribute and in these Twig contexts:
 * the ``include()`` and ``source()`` functions.
 
 Both regular names such as ``article/show.html.twig`` and namespaced names such
-as ``@Admin/dashboard.html.twig`` are supported. Static names use Twig's string
-escape semantics. Completion and navigation resolve a leading ``./`` on regular
+as ``@Admin/dashboard.html.twig`` are supported. The ``include()`` and
+``source()`` functions recognize positional and named template arguments.
+Completion expects named arguments in their declared order; navigation also
+recognizes reordered named arguments. Static names use Twig's string escape
+semantics. Completion and navigation resolve a leading ``./`` on regular
 loader-root names. Before an ``@`` prefix, it keeps the name in Twig's main
 namespace.
 

docs/features/twig-constants-enums.rst

@@ -21,8 +21,9 @@ function. Enum classes and cases are also recognized through ``enum()`` and
         {{ status.value }}
     {% endfor %}
 
-String arguments use Twig's escape semantics before PHP class and member names
-are resolved.
+Arguments are recognized positionally or by the ``constant`` and ``enum``
+names declared by the Twig functions. String arguments use Twig's escape
+semantics before PHP class and member names are resolved.
 
 Completion
 ----------

resources/services.php

@@ -72,6 +72,7 @@
 use Symfony\Lsp\Parser\TreeSitter\LastResultTreeSitterParser;
 use Symfony\Lsp\Parser\TreeSitter\NativeTreeSitterParser;
 use Symfony\Lsp\Parser\TreeSitter\TreeSitterParserInterface;
+use Symfony\Lsp\Parser\Twig\TwigCallArgumentResolver;
 use Symfony\Lsp\Parser\Twig\TwigQuotedArgumentMatcher;
 use Symfony\Lsp\Parser\Xml\XmlCommentParser;
 use Symfony\Lsp\Parser\Yaml\YamlCommentParser;
@@ -195,6 +196,7 @@
     $services->load('Symfony\\Lsp\\Parser\\', '../src/Parser/**/*{Parser,Decoder,Locator}.php');
     $services->set(BalancedDelimiterMatcher::class);
     $services->set(QuotedArgumentMatcher::class);
+    $services->set(TwigCallArgumentResolver::class);
     $services->set(TwigQuotedArgumentMatcher::class);
     $services->set(TranslationParameterAnalyzer::class);
     $services->set(XmlCommentParser::class);

src/Feature/Route/TwigRouteCompletionContext.php

@@ -19,7 +19,7 @@ public static function fromTwig(string $text, Position $position, PositionConver
         $cursor = $positionConverter->toByteOffset($text, $position);
         $beforeCursor = substr($text, 0, $cursor);
         if (!preg_match(
-            '/\b(?:path|url)\s*\(\s*([\'\"])([^\'\"]*)$/s',
+            '/\b(?:path|url)\s*\(\s*(?:name\s*[:=]\s*)?([\'\"])([^\'\"]*)$/s',
             $beforeCursor,
             $matches,
             \PREG_OFFSET_CAPTURE,

src/Feature/Route/TwigRouteParameterCompletionContext.php

@@ -24,7 +24,7 @@ public static function fromTwig(string $text, Position $position, PositionConver
         $cursor = $positionConverter->toByteOffset($text, $position);
         $beforeCursor = substr($text, 0, $cursor);
         if (!preg_match(
-            '/\b(?:path|url)\s*\(\s*([\'\"])([^\'\"]+)\1\s*,\s*\{([^}]*?)([\'\"])([^\'\"]*)$/s',
+            '/\b(?:path|url)\s*\(\s*(?:name\s*[:=]\s*)?([\'\"])([^\'\"]+)\1\s*,\s*(?:parameters\s*[:=]\s*)?\{([^}]*?)([\'\"])([^\'\"]*)$/s',
             $beforeCursor,
             $matches,
             \PREG_OFFSET_CAPTURE,

src/Feature/Route/TwigRouteReferenceExtractor.php

@@ -5,6 +5,7 @@
 use Symfony\Lsp\Document\PositionConverter;
 use Symfony\Lsp\Document\Range;
 use Symfony\Lsp\Parser\TreeSitter\TreeSitterNode;
+use Symfony\Lsp\Parser\Twig\TwigCallArgumentResolver;
 use Symfony\Lsp\Parser\Twig\TwigDocument;
 use Symfony\Lsp\Parser\Twig\TwigDocumentParser;
 
@@ -13,6 +14,7 @@ final class TwigRouteReferenceExtractor
     public function __construct(
         private readonly PositionConverter $positionConverter,
         private readonly TwigDocumentParser $parser,
+        private readonly TwigCallArgumentResolver $arguments,
     ) {
     }
 
@@ -26,17 +28,9 @@ public function extract(string $text): array
             if (null === $function || !\in_array($document->text($function), ['path', 'url'], true)) {
                 continue;
             }
-            $argumentsNode = $document->directChild($call, 'arguments');
-            if (null === $argumentsNode) {
-                continue;
-            }
-            $arguments = [];
-            foreach ($document->children($argumentsNode) as $argument) {
-                if ('argument' === $argument->type) {
-                    $arguments[] = $argument;
-                }
-            }
-            $route = isset($arguments[0]) ? $document->soleStringLiteral($arguments[0]) : null;
+            $arguments = $this->arguments->resolve($document, $call);
+            $routeArgument = $arguments->get(0, 'name');
+            $route = null === $routeArgument ? null : $document->soleStringLiteral($routeArgument);
             if (null === $route) {
                 continue;
             }
@@ -47,7 +41,7 @@ public function extract(string $text): array
                     $this->positionConverter->toPosition($text, $route->startOffset),
                     $this->positionConverter->toPosition($text, $route->endOffset),
                 ),
-                $this->providedParameters($document, $arguments[1] ?? null),
+                $this->providedParameters($document, $arguments->get(1, 'parameters')),
             );
         }
 

src/Feature/Translation/TwigTranslationReferenceExtractor.php

@@ -4,7 +4,7 @@
 
 use Symfony\Lsp\Document\PositionConverter;
 use Symfony\Lsp\Parser\TreeSitter\TreeSitterNode;
-use Symfony\Lsp\Parser\Twig\TwigArgumentParser;
+use Symfony\Lsp\Parser\Twig\TwigCallArgumentResolver;
 use Symfony\Lsp\Parser\Twig\TwigCommentParser;
 use Symfony\Lsp\Parser\Twig\TwigDocument;
 use Symfony\Lsp\Parser\Twig\TwigDocumentParser;
@@ -16,7 +16,7 @@ final class TwigTranslationReferenceExtractor
     public function __construct(
         private readonly PositionConverter $converter,
         private readonly TwigDocumentParser $parser,
-        private readonly TwigArgumentParser $argumentParser,
+        private readonly TwigCallArgumentResolver $arguments,
         private readonly TwigCommentParser $comments,
         private readonly TranslationParameterAnalyzer $parameters,
     ) {
@@ -74,8 +74,8 @@ private function filterReferences(string $uri, string $text, string $masked, Twi
             if (null === $key) {
                 continue;
             }
-            $arguments = $this->arguments($masked, $document, $filter);
-            $domain = $this->domain($document, $this->argument($arguments, 1, ['domain']), $defaultDomain);
+            $arguments = $this->arguments->resolve($document, $filter);
+            $domain = $this->domain($document, $arguments->get(1, 'domain'), $defaultDomain);
             if (null === $domain) {
                 continue;
             }
@@ -84,7 +84,7 @@ private function filterReferences(string $uri, string $text, string $masked, Twi
                 $domain,
                 $uri,
                 $text,
-                $this->parameters->twig($document, $this->argument($arguments, 0, ['arguments', 'parameters'])),
+                $this->parameters->twig($document, $arguments->get(0, 'arguments', 'parameters')),
             );
         }
 
@@ -122,10 +122,10 @@ private function functionReferences(string $uri, string $text, string $masked, T
             if (null === $identifier || !\in_array($document->text($identifier), ['trans', 't'], true)) {
                 continue;
             }
-            $arguments = $this->arguments($masked, $document, $call);
-            $keyArgument = $this->argument($arguments, 0, ['id', 'message']);
+            $arguments = $this->arguments->resolve($document, $call);
+            $keyArgument = $arguments->get(0, 'id', 'message');
             $key = null === $keyArgument ? null : $document->soleStringLiteral($keyArgument);
-            $domain = $this->domain($document, $this->argument($arguments, 2, ['domain']), $defaultDomain);
+            $domain = $this->domain($document, $arguments->get(2, 'domain'), $defaultDomain);
             if (null === $key || null === $domain) {
                 continue;
             }
@@ -134,70 +134,13 @@ private function functionReferences(string $uri, string $text, string $masked, T
                 $domain,
                 $uri,
                 $text,
-                $this->parameters->twig($document, $this->argument($arguments, 1, ['arguments', 'parameters'])),
+                $this->parameters->twig($document, $arguments->get(1, 'arguments', 'parameters')),
             );
         }
 
         return $references;
     }
 
-    /** @return list<array{name: string|null, value: TreeSitterNode}> */
-    private function arguments(string $masked, TwigDocument $document, TreeSitterNode $call): array
-    {
-        $container = $document->directChild($call, 'arguments');
-        if (null === $container) {
-            return [];
-        }
-
-        $text = substr($masked, $container->startByte, $container->endByte - $container->startByte);
-        $offset = $container->startByte;
-        if (str_starts_with($text, '(')) {
-            $text = substr($text, 1);
-            ++$offset;
-        }
-        if (str_ends_with($text, ')')) {
-            $text = substr($text, 0, -1);
-        }
-
-        $parsed = $this->argumentParser->parse($text, $offset);
-        $arguments = [];
-        foreach ($document->children($container) as $child) {
-            if ('argument' !== $child->type) {
-                continue;
-            }
-            $value = $document->directChild($child, 'argument_value') ?? $child;
-            $name = null;
-            foreach ($parsed as $argument) {
-                if ($value->startByte >= $argument->offset && $value->startByte < $argument->offset + \strlen($argument->text)) {
-                    $name = $argument->name;
-
-                    break;
-                }
-            }
-            $arguments[] = ['name' => $name, 'value' => $value];
-        }
-
-        return $arguments;
-    }
-
-    /**
-     * @param list<array{name: string|null, value: TreeSitterNode}> $arguments
-     * @param list<string>                                          $names
-     */
-    private function argument(array $arguments, int $position, array $names): ?TreeSitterNode
-    {
-        $positional = [];
-        foreach ($arguments as $argument) {
-            if (null === $argument['name']) {
-                $positional[] = $argument['value'];
-            } elseif (\in_array($argument['name'], $names, true)) {
-                return $argument['value'];
-            }
-        }
-
-        return $positional[$position] ?? null;
-    }
-
     private function domain(TwigDocument $document, ?TreeSitterNode $argument, string $defaultDomain): ?string
     {
         return null === $argument ? $defaultDomain : $document->soleStringLiteral($argument)?->value;

src/Feature/Twig/TemplateCompletionContext.php

@@ -19,7 +19,7 @@ public static function create(string $languageId, string $text, Position $positi
         $pattern = 'php' === $languageId
             ? '/(?:(?:->|::)(?:render|renderView)\s*\(|#\[\s*(?:[^\[\]]*,\s*)?\\\\?(?:Symfony\\\\Bridge\\\\Twig\\\\Attribute\\\\)?Template\s*\(\s*(?:template\s*:)?)\s*([\'\"])([^\'\"]*)$/s'
             : ('twig' === $languageId
-                ? '/(?:(?:{%\s*(?:extends|include|embed|import|from|use)\s+)|(?:\b(?:include|source)\s*\())([\'\"])([^\'\"]*)$/s'
+                ? '/(?:(?:{%\s*(?:extends|include|embed|import|from|use)\s+)|(?:\binclude\s*\(\s*(?:template\s*[:=]\s*)?)|(?:\bsource\s*\(\s*(?:name\s*[:=]\s*)?))([\'\"])([^\'\"]*)$/s'
                 : null);
         if (null === $pattern || !preg_match($pattern, $before, $matches, \PREG_OFFSET_CAPTURE)) {
             return null;