feat: add CallLike::getArg() method

This method returns the named argument that matches the given `$name`,
or the positional (unnamed) argument that exists at the given `$position`,
otherwise, returns `null` for first-class callables or if no match is found.

Author: calebdw

lib/PhpParser/Node/Expr/CallLike.php

@@ -32,4 +32,29 @@ public function getArgs(): array {
         assert(!$this->isFirstClassCallable());
         return $this->getRawArgs();
     }
+
+    /**
+     * Retrieves a specific argument from the raw arguments.
+     *
+     * Returns the named argument that matches the given `$name`, or the
+     * positional (unnamed) argument that exists at the given `$position`,
+     * otherwise, returns `null` for first-class callables or if no match is found.
+     */
+    public function getArg(string $name, int $position): ?Arg {
+        if ($this->isFirstClassCallable()) {
+            return null;
+        }
+        foreach ($this->getRawArgs() as $i => $arg) {
+            if ($arg->unpack) {
+                continue;
+            }
+            if (
+                ($arg->name !== null && $arg->name->toString() === $name)
+                || ($arg->name === null && $i === $position)
+            ) {
+                return $arg;
+            }
+        }
+        return null;
+    }
 }

test/PhpParser/Node/Expr/CallableLikeTest.php

@@ -3,6 +3,7 @@
 namespace PhpParser\Node\Expr;
 
 use PhpParser\Node\Arg;
+use PhpParser\Node\Identifier;
 use PhpParser\Node\Name;
 use PhpParser\Node\Scalar\Int_;
 use PhpParser\Node\VariadicPlaceholder;
@@ -18,6 +19,13 @@ public function testIsFirstClassCallable(CallLike $node, bool $isFirstClassCalla
         }
     }
 
+    /**
+     * @dataProvider provideTestGetArg
+     */
+    public function testGetArg(CallLike $node, ?Arg $expected): void {
+        $this->assertSame($expected, $node->getArg('bar', 1));
+    }
+
     public static function provideTestIsFirstClassCallable() {
         $normalArgs = [new Arg(new Int_(1))];
         $callableArgs = [new VariadicPlaceholder()];
@@ -35,4 +43,56 @@ public static function provideTestIsFirstClassCallable() {
             [new NullsafeMethodCall(new Variable('this'), 'test', $callableArgs), true],
         ];
     }
+
+    public static function provideTestGetArg() {
+        $foo = new Arg(new Int_(1));
+        $namedFoo = new Arg(new Int_(1), false, false, [], new Identifier('foo'));
+        $bar = new Arg(new Int_(2));
+        $namedBar = new Arg(new Int_(2), false, false, [], new Identifier('bar'));
+        $unpack = new Arg(new Int_(3), false, true);
+        $callableArgs = [new VariadicPlaceholder()];
+        return [
+            [new FuncCall(new Name('test'), [$foo]), null],
+            [new FuncCall(new Name('test'), [$namedFoo]), null],
+            [new FuncCall(new Name('test'), [$foo, $bar]), $bar],
+            [new FuncCall(new Name('test'), [$namedBar]), $namedBar],
+            [new FuncCall(new Name('test'), [$namedFoo, $namedBar]), $namedBar],
+            [new FuncCall(new Name('test'), [$namedBar, $namedFoo]), $namedBar],
+            [new FuncCall(new Name('test'), [$namedFoo, $unpack]), null],
+            [new FuncCall(new Name('test'), $callableArgs), null],
+            [new MethodCall(new Variable('this'), 'test', [$foo]), null],
+            [new MethodCall(new Variable('this'), 'test', [$namedFoo]), null],
+            [new MethodCall(new Variable('this'), 'test', [$foo, $bar]), $bar],
+            [new MethodCall(new Variable('this'), 'test', [$namedBar]), $namedBar],
+            [new MethodCall(new Variable('this'), 'test', [$namedFoo, $namedBar]), $namedBar],
+            [new MethodCall(new Variable('this'), 'test', [$namedBar, $namedFoo]), $namedBar],
+            [new MethodCall(new Variable('this'), 'test', [$namedFoo, $unpack]), null],
+            [new MethodCall(new Variable('this'), 'test', $callableArgs), null],
+            [new StaticCall(new Name('Test'), 'test', [$foo]), null],
+            [new StaticCall(new Name('Test'), 'test', [$namedFoo]), null],
+            [new StaticCall(new Name('Test'), 'test', [$foo, $bar]), $bar],
+            [new StaticCall(new Name('Test'), 'test', [$namedBar]), $namedBar],
+            [new StaticCall(new Name('Test'), 'test', [$namedFoo, $namedBar]), $namedBar],
+            [new StaticCall(new Name('Test'), 'test', [$namedBar, $namedFoo]), $namedBar],
+            [new StaticCall(new Name('Test'), 'test', [$namedFoo, $unpack]), null],
+            [new StaticCall(new Name('Test'), 'test', $callableArgs), null],
+            [new New_(new Name('test'), [$foo]), null],
+            [new New_(new Name('test'), [$namedFoo]), null],
+            [new New_(new Name('test'), [$foo, $bar]), $bar],
+            [new New_(new Name('test'), [$namedBar]), $namedBar],
+            [new New_(new Name('test'), [$namedFoo, $namedBar]), $namedBar],
+            [new New_(new Name('test'), [$namedBar, $namedFoo]), $namedBar],
+            [new New_(new Name('test'), [$namedFoo, $unpack]), null],
+            [new NullsafeMethodCall(new Variable('this'), 'test', [$foo]), null],
+            [new NullsafeMethodCall(new Variable('this'), 'test', [$namedFoo]), null],
+            [new NullsafeMethodCall(new Variable('this'), 'test', [$foo, $bar]), $bar],
+            [new NullsafeMethodCall(new Variable('this'), 'test', [$namedBar]), $namedBar],
+            [new NullsafeMethodCall(new Variable('this'), 'test', [$namedFoo, $namedBar]), $namedBar],
+            [new NullsafeMethodCall(new Variable('this'), 'test', [$namedBar, $namedFoo]), $namedBar],
+            [new NullsafeMethodCall(new Variable('this'), 'test', [$namedFoo, $unpack]), null],
+            // This is not legal code, but accepted by the parser.
+            [new New_(new Name('Test'), $callableArgs), null],
+            [new NullsafeMethodCall(new Variable('this'), 'test', $callableArgs), null],
+        ];
+    }
 }