added Arrays::invoke() and invokeMethod() return type narrowing

Author: dg

CLAUDE.md

@@ -65,6 +65,10 @@ Extensions for specific Nette packages use dedicated namespaces: `Nette\PHPStan\
 
 `StringsReturnTypeExtension` (`DynamicStaticMethodReturnTypeExtension`) narrows return types of `Strings::match()`, `matchAll()` and `split()` based on boolean arguments. It resolves `captureOffset`, `unmatchedAsNull`, `patternOrder`, and `lazy` to constant booleans and constructs the precise return type — e.g. `match()` with `captureOffset: true` returns `array<array{string, int<0, max>}>|null` instead of `?array`. When a boolean argument is not a constant, falls back to the declared return type. Config: `extension-nette.neon`.
 
+### ArraysInvokeTypeExtension
+
+`ArraysInvokeTypeExtension` (`DynamicStaticMethodReturnTypeExtension`) narrows return types of `Arrays::invoke()` and `Arrays::invokeMethod()` from `array`. For `invoke()`, it extracts the callable return type from the iterable value type and forwards `...$args` via `ParametersAcceptorSelector::selectFromArgs()` to resolve the correct overload. For `invokeMethod()`, it resolves constant method names on the object type, gets method reflection, and forwards remaining args. Handles `callable(): void` by converting void to null. Falls back to declared return type when callbacks are not callable, method names are not constant strings, or methods don't exist on the object type. Config: `extension-nette.neon`.
+
 ### AssertTypeNarrowingExtension
 
 `AssertTypeNarrowingExtension` (`StaticMethodTypeSpecifyingExtension` + `TypeSpecifierAwareExtension`) narrows variable types after `Tester\Assert` assertion calls. Each assertion method is mapped to an equivalent PHP expression that PHPStan already understands, then delegated to `TypeSpecifier::specifyTypesInCondition()`. Supported methods: `null`, `notNull`, `true`, `false`, `truthy`, `falsey`, `same`, `notSame`, and `type` (with built-in type strings like `'string'`, `'int'`, etc. and class/interface names). Config: `extension-nette.neon`.

extension-nette.neon

@@ -28,3 +28,6 @@ services:
 	-
 		class: Nette\PHPStan\Utils\StringsReturnTypeExtension
 		tags: [phpstan.broker.dynamicStaticMethodReturnTypeExtension]
+	-
+		class: Nette\PHPStan\Utils\ArraysInvokeTypeExtension
+		tags: [phpstan.broker.dynamicStaticMethodReturnTypeExtension]

readme.md

@@ -41,7 +41,7 @@ includes:
 
  <!---->
 
-**Precise return types** — narrows return types of `Strings::match()`, `matchAll()`, `split()`, `Helpers::falseToNull()`, and `Expect::array()` based on the arguments you pass.
+**Precise return types** — narrows return types of `Strings::match()`, `matchAll()`, `split()`, `Helpers::falseToNull()`, `Expect::array()`, `Arrays::invoke()`, and `Arrays::invokeMethod()` based on the arguments you pass.
 
 **Removes `|false` and `|null` from PHP functions** — many native functions like `getcwd`, `json_encode`, `preg_split`, `preg_replace`, and [many more](extension-php.neon) include `false` or `null` in their return type even though these error values are unrealistic on modern systems.
 

src/Utils/ArraysInvokeTypeExtension.php

@@ -0,0 +1,116 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nette\PHPStan\Utils;
+
+use PhpParser\Node\Expr\StaticCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\ParametersAcceptorSelector;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\DynamicStaticMethodReturnTypeExtension;
+use PHPStan\Type\NullType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use function array_slice, count, in_array;
+
+
+/**
+ * Narrows return types of Arrays::invoke() and Arrays::invokeMethod()
+ * by resolving callback/method return types and forwarding arguments.
+ */
+class ArraysInvokeTypeExtension implements DynamicStaticMethodReturnTypeExtension
+{
+	public function getClass(): string
+	{
+		return 'Nette\Utils\Arrays';
+	}
+
+
+	public function isStaticMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return in_array($methodReflection->getName(), ['invoke', 'invokeMethod'], true);
+	}
+
+
+	public function getTypeFromStaticMethodCall(
+		MethodReflection $methodReflection,
+		StaticCall $methodCall,
+		Scope $scope,
+	): ?Type
+	{
+		return match ($methodReflection->getName()) {
+			'invoke' => $this->resolveInvoke($methodCall, $scope),
+			'invokeMethod' => $this->resolveInvokeMethod($methodCall, $scope),
+			default => null,
+		};
+	}
+
+
+	private function resolveInvoke(StaticCall $call, Scope $scope): ?Type
+	{
+		$args = $call->getArgs();
+		if ($args === []) {
+			return null;
+		}
+
+		$callbacksType = $scope->getType($args[0]->value);
+		$callbackType = $callbacksType->getIterableValueType();
+
+		if (!$callbackType->isCallable()->yes()) {
+			return null;
+		}
+
+		$acceptors = $callbackType->getCallableParametersAcceptors($scope);
+		$forwardedArgs = array_slice($args, 1);
+		$selected = ParametersAcceptorSelector::selectFromArgs($scope, $forwardedArgs, $acceptors);
+		$returnType = self::voidToNull($selected->getReturnType());
+
+		return new ArrayType($callbacksType->getIterableKeyType(), $returnType);
+	}
+
+
+	private function resolveInvokeMethod(StaticCall $call, Scope $scope): ?Type
+	{
+		$args = $call->getArgs();
+		if (count($args) < 2) {
+			return null;
+		}
+
+		$objectsType = $scope->getType($args[0]->value);
+		$objectType = $objectsType->getIterableValueType();
+
+		$constantStrings = $scope->getType($args[1]->value)->getConstantStrings();
+		if ($constantStrings === []) {
+			return null;
+		}
+
+		$forwardedArgs = array_slice($args, 2);
+		$returnTypes = [];
+
+		foreach ($constantStrings as $constantString) {
+			$methodName = $constantString->getValue();
+			if (!$objectType->hasMethod($methodName)->yes()) {
+				return null;
+			}
+
+			$methodReflection = $objectType->getMethod($methodName, $scope);
+			$selected = ParametersAcceptorSelector::selectFromArgs(
+				$scope,
+				$forwardedArgs,
+				$methodReflection->getVariants(),
+			);
+			$returnTypes[] = $selected->getReturnType();
+		}
+
+		$returnType = self::voidToNull(TypeCombinator::union(...$returnTypes));
+		return new ArrayType($objectsType->getIterableKeyType(), $returnType);
+	}
+
+
+	private static function voidToNull(Type $type): Type
+	{
+		return $type->isVoid()->yes() ? new NullType : $type;
+	}
+}

tests/Utils/arrays-invoke-return-type.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+use Nette\Utils\Arrays;
+use function PHPStan\Testing\assertType;
+
+
+// invoke() — typed closures
+
+
+/** @param array<callable(): string> $callbacks */
+function testInvokeString(array $callbacks): void
+{
+	assertType('array<string>', Arrays::invoke($callbacks));
+}
+
+
+/** @param array<callable(): int> $callbacks */
+function testInvokeInt(array $callbacks): void
+{
+	assertType('array<int>', Arrays::invoke($callbacks));
+}
+
+
+// invoke() — string-keyed array preserves keys
+
+
+/** @param array<string, callable(): string> $callbacks */
+function testInvokeStringKeys(array $callbacks): void
+{
+	assertType('array<string, string>', Arrays::invoke($callbacks));
+}
+
+
+// invoke() — forwarding args
+
+
+/** @param array<callable(string): string> $callbacks */
+function testInvokeForwardArgs(array $callbacks): void
+{
+	assertType('array<string>', Arrays::invoke($callbacks, 'hello'));
+}
+
+
+/** @param array<callable(int, int): int> $callbacks */
+function testInvokeForwardMultipleArgs(array $callbacks): void
+{
+	assertType('array<int>', Arrays::invoke($callbacks, 1, 2));
+}
+
+
+// invoke() — callable(): void
+
+
+/** @param list<callable(): void> $callbacks */
+function testInvokeVoid(array $callbacks): void
+{
+	assertType('array<int<0, max>, null>', Arrays::invoke($callbacks));
+}
+
+
+// invoke() — typed callable parameter
+
+
+/** @param array<string, callable(): bool> $callbacks */
+function testInvokeTypedCallable(array $callbacks): void
+{
+	assertType('array<string, bool>', Arrays::invoke($callbacks));
+}
+
+
+// invokeMethod() — known class and method
+
+
+/** @param array<DateTimeImmutable> $objects */
+function testInvokeMethodTimestamp(array $objects): void
+{
+	assertType('array<int>', Arrays::invokeMethod($objects, 'getTimestamp'));
+}
+
+
+// invokeMethod() — string keys preserved
+
+
+/** @param array<string, DateTimeImmutable> $objects */
+function testInvokeMethodStringKeys(array $objects): void
+{
+	assertType('array<string, int>', Arrays::invokeMethod($objects, 'getTimestamp'));
+}
+
+
+// invokeMethod() — forwarding args
+
+
+/** @param array<DateTimeImmutable> $objects */
+function testInvokeMethodFormat(array $objects): void
+{
+	assertType('array<string>', Arrays::invokeMethod($objects, 'format', 'Y-m-d'));
+}

tests/extensions.phpt

@@ -19,3 +19,4 @@ TypeAssert::assertTypes(__DIR__ . '/Tester/assert-in-function.php');
 // Utils
 TypeAssert::assertTypes(__DIR__ . '/Utils/false-to-null-return-type.php');
 TypeAssert::assertTypes(__DIR__ . '/Utils/strings-return-type.php');
+TypeAssert::assertTypes(__DIR__ . '/Utils/arrays-invoke-return-type.php');