Extract a new CallableArgumentsExtractor class

CHANGELOG

@@ -1,5 +1,6 @@
 # 3.12.0 (2024-XX-XX)
 
+ * Add a `CallableArgumentsExtractor` class
  * Deprecate passing a name to `FunctionExpression`, `FilterExpression`, and `TestExpression`;
    pass a `TwigFunction`, `TwigFilter`, or `TestFilter` instead
  * Deprecate all Twig callable attributes on `TwigFunction`, `TwigFilter`, and `TestFilter`

src/Node/Expression/CallExpression.php

@@ -19,6 +19,7 @@ use Twig\TwigCallableInterface;
 use Twig\TwigFilter;
 use Twig\TwigFunction;
 use Twig\TwigTest;
+use Twig\Util\CallableArgumentsExtractor;
 use Twig\Util\ReflectionCallable;
 
 abstract class CallExpression extends AbstractExpression
@@ -113,8 +114,7 @@ abstract class CallExpression extends AbstractExpression
         }
 
         if ($this->hasNode('arguments')) {
-            $callable = $twigCallable->getCallable();
-            $arguments = $this->getArguments($callable, $this->getNode('arguments'));
+            $arguments = (new CallableArgumentsExtractor($this, $this->getTwigCallable()))->extractArguments($this->getNode('arguments'));
             foreach ($arguments as $node) {
                 if (!$first) {
                     $compiler->raw(', ');
@@ -127,8 +127,13 @@ abstract class CallExpression extends AbstractExpression
         $compiler->raw($isArray ? ']' : ')');
     }
 
+    /**
+     * @deprecated since 3.12, use Twig\Util\CallableArgumentsExtractor::getArguments() instead
+     */
     protected function getArguments($callable, $arguments)
     {
+        trigger_deprecation('twig/twig', '3.12', 'The "%s()" method is deprecated, use Twig\Util\CallableArgumentsExtractor::getArguments() instead.', __METHOD__);
+
         $callType = $this->getAttribute('type');
         $callName = $this->getAttribute('name');
 
@@ -252,11 +257,17 @@ abstract class CallExpression extends AbstractExpression
         return $arguments;
     }
 
+    /**
+     * @deprecated since 3.12
+     */
     protected function normalizeName(string $name): string
     {
+        trigger_deprecation('twig/twig', '3.12', 'The "%s()" method is deprecated.', __METHOD__);
+
         return strtolower(preg_replace(['/([A-Z]+)([A-Z][a-z])/', '/([a-z\d])([A-Z])/'], ['\\1_\\2', '\\1_\\2'], $name));
     }
 
+    // To be removed in 4.0
     private function getCallableParameters($callable, bool $isVariadic): array
     {
         $twigCallable = $this->getAttribute('twig_callable');

src/Util/CallableArgumentsExtractor.php

@@ -0,0 +1,215 @@
+<?php
+
+/*
+ * This file is part of Twig.
+ *
+ * (c) Fabien Potencier
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Twig\Util;
+
+use Twig\Error\SyntaxError;
+use Twig\Node\Expression\ArrayExpression;
+use Twig\Node\Expression\ConstantExpression;
+use Twig\Node\Expression\VariadicExpression;
+use Twig\Node\Node;
+use Twig\TwigCallableInterface;
+use Twig\TwigFilter;
+use Twig\TwigFunction;
+use Twig\TwigTest;
+
+/**
+ * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @internal
+ */
+final class CallableArgumentsExtractor
+{
+    private string $type;
+    private string $name;
+
+    public function __construct(
+        private Node $node,
+        private TwigCallableInterface $twigCallable,
+    ) {
+        $this->type = match (true) {
+            $twigCallable instanceof TwigFunction => 'function',
+            $twigCallable instanceof TwigFilter => 'filter',
+            $twigCallable instanceof TwigTest => 'test',
+            default => throw new \LogicException('Unknown callable type.'),
+        };
+        $this->name = $twigCallable->getName();
+    }
+
+    /**
+     * @return array<Node>
+     */
+    public function extractArguments(Node $arguments): array
+    {
+        $parameters = [];
+        $named = false;
+        foreach ($arguments as $name => $node) {
+            if (!\is_int($name)) {
+                $named = true;
+                $name = $this->normalizeName($name);
+            } elseif ($named) {
+                throw new SyntaxError(\sprintf('Positional arguments cannot be used after named arguments for %s "%s".', $this->type, $this->name), $this->node->getTemplateLine(), $this->node->getSourceContext());
+            }
+
+            $parameters[$name] = $node;
+        }
+
+        if (!$named && !$this->twigCallable->isVariadic()) {
+            return $parameters;
+        }
+
+        if (!$callable = $this->twigCallable->getCallable()) {
+            if ($named) {
+                $message = \sprintf('Named arguments are not supported for %s "%s".', $this->type, $this->name);
+            } else {
+                $message = \sprintf('Arbitrary positional arguments are not supported for %s "%s".', $this->type, $this->name);
+            }
+
+            throw new \LogicException($message);
+        }
+
+        [$callableParameters, $isPhpVariadic] = $this->getCallableParameters();
+        $arguments = [];
+        $names = [];
+        $missingArguments = [];
+        $optionalArguments = [];
+        $pos = 0;
+        foreach ($callableParameters as $callableParameter) {
+            $name = $this->normalizeName($callableParameter->name);
+            if (\PHP_VERSION_ID >= 80000 && 'range' === $callable) {
+                if ('start' === $name) {
+                    $name = 'low';
+                } elseif ('end' === $name) {
+                    $name = 'high';
+                }
+            }
+
+            $names[] = $name;
+
+            if (\array_key_exists($name, $parameters)) {
+                if (\array_key_exists($pos, $parameters)) {
+                    throw new SyntaxError(\sprintf('Argument "%s" is defined twice for %s "%s".', $name, $this->type, $this->name), $this->node->getTemplateLine(), $this->node->getSourceContext());
+                }
+
+                if (\count($missingArguments)) {
+                    throw new SyntaxError(\sprintf(
+                        'Argument "%s" could not be assigned for %s "%s(%s)" because it is mapped to an internal PHP function which cannot determine default value for optional argument%s "%s".',
+                        $name, $this->type, $this->name, implode(', ', $names), \count($missingArguments) > 1 ? 's' : '', implode('", "', $missingArguments)
+                    ), $this->node->getTemplateLine(), $this->node->getSourceContext());
+                }
+
+                $arguments = array_merge($arguments, $optionalArguments);
+                $arguments[] = $parameters[$name];
+                unset($parameters[$name]);
+                $optionalArguments = [];
+            } elseif (\array_key_exists($pos, $parameters)) {
+                $arguments = array_merge($arguments, $optionalArguments);
+                $arguments[] = $parameters[$pos];
+                unset($parameters[$pos]);
+                $optionalArguments = [];
+                ++$pos;
+            } elseif ($callableParameter->isDefaultValueAvailable()) {
+                $optionalArguments[] = new ConstantExpression($callableParameter->getDefaultValue(), -1);
+            } elseif ($callableParameter->isOptional()) {
+                if (empty($parameters)) {
+                    break;
+                } else {
+                    $missingArguments[] = $name;
+                }
+            } else {
+                throw new SyntaxError(\sprintf('Value for argument "%s" is required for %s "%s".', $name, $this->type, $this->name), $this->node->getTemplateLine(), $this->node->getSourceContext());
+            }
+        }
+
+        if ($this->twigCallable->isVariadic()) {
+            $arbitraryArguments = $isPhpVariadic ? new VariadicExpression([], -1) : new ArrayExpression([], -1);
+            foreach ($parameters as $key => $value) {
+                if (\is_int($key)) {
+                    $arbitraryArguments->addElement($value);
+                } else {
+                    $arbitraryArguments->addElement($value, new ConstantExpression($key, -1));
+                }
+                unset($parameters[$key]);
+            }
+
+            if ($arbitraryArguments->count()) {
+                $arguments = array_merge($arguments, $optionalArguments);
+                $arguments[] = $arbitraryArguments;
+            }
+        }
+
+        if (!empty($parameters)) {
+            $unknownParameter = null;
+            foreach ($parameters as $parameter) {
+                if ($parameter instanceof Node) {
+                    $unknownParameter = $parameter;
+                    break;
+                }
+            }
+
+            throw new SyntaxError(
+                \sprintf(
+                    'Unknown argument%s "%s" for %s "%s(%s)".',
+                    \count($parameters) > 1 ? 's' : '', implode('", "', array_keys($parameters)), $this->type, $this->name, implode(', ', $names)
+                ),
+                $unknownParameter ? $unknownParameter->getTemplateLine() : $this->node->getTemplateLine(),
+                $unknownParameter ? $unknownParameter->getSourceContext() : $this->node->getSourceContext()
+            );
+        }
+
+        return $arguments;
+    }
+
+    private function normalizeName(string $name): string
+    {
+        return strtolower(preg_replace(['/([A-Z]+)([A-Z][a-z])/', '/([a-z\d])([A-Z])/'], ['\\1_\\2', '\\1_\\2'], $name));
+    }
+
+    private function getCallableParameters(): array
+    {
+        $rc = new ReflectionCallable($this->twigCallable->getCallable(), $this->type, $this->name);
+        $r = $rc->getReflector();
+        $callableName = $rc->getName();
+
+        $parameters = $r->getParameters();
+        if ($this->node->hasNode('node')) {
+            array_shift($parameters);
+        }
+        if ($this->twigCallable->needsCharset()) {
+            array_shift($parameters);
+        }
+        if ($this->twigCallable->needsEnvironment()) {
+            array_shift($parameters);
+        }
+        if ($this->twigCallable->needsContext()) {
+            array_shift($parameters);
+        }
+        foreach ($this->twigCallable->getArguments() as $argument) {
+            array_shift($parameters);
+        }
+
+        $isPhpVariadic = false;
+        if ($this->twigCallable->isVariadic()) {
+            $argument = end($parameters);
+            $isArray = $argument && $argument->hasType() && $argument->getType() instanceof \ReflectionNamedType && 'array' === $argument->getType()->getName();
+            if ($isArray && $argument->isDefaultValueAvailable() && [] === $argument->getDefaultValue()) {
+                array_pop($parameters);
+            } elseif ($argument && $argument->isVariadic()) {
+                array_pop($parameters);
+                $isPhpVariadic = true;
+            } else {
+                throw new \LogicException(\sprintf('The last parameter of "%s" for %s "%s" must be an array with default value, eg. "array $arg = []".', $callableName, $this->type, $this->name));
+            }
+        }
+
+        return [$parameters, $isPhpVariadic];
+    }
+}

tests/Node/Expression/CallTest.php

@@ -17,6 +17,9 @@ use Twig\Node\Expression\FunctionExpression;
 use Twig\Node\Node;
 use Twig\TwigFunction;
 
+/**
+ * @group legacy
+ */
 class CallTest extends TestCase
 {
     public function testGetArguments()

tests/Util/CallableArgumentsExtractorTest.php

@@ -0,0 +1,156 @@
+<?php
+
+namespace Twig\Tests\Util;
+
+/*
+ * This file is part of Twig.
+ *
+ * (c) Fabien Potencier
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use PHPUnit\Framework\TestCase;
+use Twig\Error\SyntaxError;
+use Twig\Node\Expression\ConstantExpression;
+use Twig\Node\Expression\FunctionExpression;
+use Twig\Node\Node;
+use Twig\TwigFunction;
+use Twig\Util\CallableArgumentsExtractor;
+
+class CallableArgumentsExtractorTest extends TestCase
+{
+    public function testGetArguments()
+    {
+        $this->assertEquals(['U', null], $this->getArguments('date', 'date', ['format' => 'U', 'timestamp' => null]));
+    }
+
+    public function testGetArgumentsWhenPositionalArgumentsAfterNamedArguments()
+    {
+        $this->expectException(SyntaxError::class);
+        $this->expectExceptionMessage('Positional arguments cannot be used after named arguments for function "date".');
+
+        $this->getArguments('date', 'date', ['timestamp' => 123456, 'Y-m-d']);
+    }
+
+    public function testGetArgumentsWhenArgumentIsDefinedTwice()
+    {
+        $this->expectException(SyntaxError::class);
+        $this->expectExceptionMessage('Argument "format" is defined twice for function "date".');
+
+        $this->getArguments('date', 'date', ['Y-m-d', 'format' => 'U']);
+    }
+
+    public function testGetArgumentsWithWrongNamedArgumentName()
+    {
+        $this->expectException(SyntaxError::class);
+        $this->expectExceptionMessage('Unknown argument "unknown" for function "date(format, timestamp)".');
+
+        $this->getArguments('date', 'date', ['Y-m-d', 'timestamp' => null, 'unknown' => '']);
+    }
+
+    public function testGetArgumentsWithWrongNamedArgumentNames()
+    {
+        $this->expectException(SyntaxError::class);
+        $this->expectExceptionMessage('Unknown arguments "unknown1", "unknown2" for function "date(format, timestamp)".');
+
+        $this->getArguments('date', 'date', ['Y-m-d', 'timestamp' => null, 'unknown1' => '', 'unknown2' => '']);
+    }
+
+    public function testResolveArgumentsWithMissingValueForOptionalArgument()
+    {
+        if (\PHP_VERSION_ID >= 80000) {
+            $this->markTestSkipped('substr_compare() has a default value in 8.0, so the test does not work anymore, one should find another PHP built-in function for this test to work in PHP 8.');
+        }
+
+        $this->expectException(SyntaxError::class);
+        $this->expectExceptionMessage('Argument "case_sensitivity" could not be assigned for function "substr_compare(main_str, str, offset, length, case_sensitivity)" because it is mapped to an internal PHP function which cannot determine default value for optional argument "length".');
+
+        $this->getArguments('substr_compare', 'substr_compare', ['abcd', 'bc', 'offset' => 1, 'case_sensitivity' => true]);
+    }
+
+    public function testResolveArgumentsOnlyNecessaryArgumentsForCustomFunction()
+    {
+        $this->assertEquals(['arg1'], $this->getArguments('custom_function', [$this, 'customFunction'], ['arg1' => 'arg1']));
+    }
+
+    public function testGetArgumentsForStaticMethod()
+    {
+        $this->assertEquals(['arg1'], $this->getArguments('custom_static_function', __CLASS__.'::customStaticFunction', ['arg1' => 'arg1']));
+    }
+
+    public function testResolveArgumentsWithMissingParameterForArbitraryArguments()
+    {
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('The last parameter of "Twig\\Tests\\Util\\CallableArgumentsExtractorTest::customFunctionWithArbitraryArguments" for function "foo" must be an array with default value, eg. "array $arg = []".');
+
+        $this->getArguments('foo', [$this, 'customFunctionWithArbitraryArguments'], [], true);
+    }
+
+    public function testGetArgumentsWithInvalidCallable()
+    {
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('Callback for function "foo" is not callable in the current scope.');
+        $this->getArguments('foo', '<not-a-callable>', [], true);
+    }
+
+    public function testResolveArgumentsWithMissingParameterForArbitraryArgumentsOnFunction()
+    {
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessageMatches('#^The last parameter of "Twig\\\\Tests\\\\Util\\\\custom_call_test_function" for function "foo" must be an array with default value, eg\\. "array \\$arg \\= \\[\\]"\\.$#');
+
+        $this->getArguments('foo', 'Twig\Tests\Util\custom_call_test_function', [], true);
+    }
+
+    public function testResolveArgumentsWithMissingParameterForArbitraryArgumentsOnObject()
+    {
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessageMatches('#^The last parameter of "Twig\\\\Tests\\\\Util\\\\CallableTestClass\\:\\:__invoke" for function "foo" must be an array with default value, eg\\. "array \\$arg \\= \\[\\]"\\.$#');
+
+        $this->getArguments('foo', new CallableTestClass(), [], true);
+    }
+
+    public static function customStaticFunction($arg1, $arg2 = 'default', $arg3 = [])
+    {
+    }
+
+    public function customFunction($arg1, $arg2 = 'default', $arg3 = [])
+    {
+    }
+
+    public function customFunctionWithArbitraryArguments()
+    {
+    }
+
+    private function getArguments(string $name, $callable, array $args, bool $isVariadic = false): array
+    {
+        $function = new TwigFunction($name, $callable, ['is_variadic' => $isVariadic]);
+        $node = new ExpressionCall($function, new Node([]), 0);
+        foreach ($args as $name => $arg) {
+            $args[$name] = new ConstantExpression($arg, 0);
+        }
+
+        $arguments = (new CallableArgumentsExtractor($node, $function))->extractArguments(new Node($args));
+        foreach ($arguments as $name => $argument) {
+            $arguments[$name] = $argument->getAttribute('value');
+        }
+
+        return $arguments;
+    }
+}
+
+class ExpressionCall extends FunctionExpression
+{
+}
+
+class CallableTestClass
+{
+    public function __invoke($required)
+    {
+    }
+}
+
+function custom_call_test_function($required)
+{
+}