Type each invocation of a closure with its own arguments

A closure whose signature is inferred from its invocations joins the
arguments of all of them - a closure invoked with Country::class and
Region::class returned list<Country|Region> at both calls. Invoked with
arguments narrower than the joined parameters, the closure now returns
what its body returns for these arguments: the body is typed like a
closure passed to a callable taking them, once per distinct signature.

The invoked variable holds the closure it is assigned in the body or, for a
captured variable, in a body enclosing it, when its type is the type the
closure was created with.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VpbB99tJfUmeArX74xqvHv

Author: ondrejmirtes

src/Analyser/ExprHandler/FuncCallHandler.php

@@ -27,6 +27,7 @@
 use PHPStan\Analyser\ExprHandler\Helper\DynamicReturnTypeStoragePrimer;
 use PHPStan\Analyser\ExprHandler\Helper\EarlyTerminatingCallHelper;
 use PHPStan\Analyser\ExprHandler\Helper\FuncCallScopeEffectsHelper;
+use PHPStan\Analyser\Generics\ClosureSignatureInference;
 use PHPStan\Analyser\Generics\TemplateArgumentFrame;
 use PHPStan\Analyser\ImpurePoint;
 use PHPStan\Analyser\InternalThrowPoint;
@@ -52,21 +53,26 @@
 use PHPStan\Reflection\Callables\SimpleThrowPoint;
 use PHPStan\Reflection\ExtendedParametersAcceptor;
 use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Reflection\Native\NativeParameterReflection;
 use PHPStan\Reflection\ParametersAcceptor;
 use PHPStan\Reflection\ParametersAcceptorSelector;
+use PHPStan\Reflection\PassedByReference;
 use PHPStan\Reflection\ReflectionProvider;
 use PHPStan\Rules\Comparison\ImpossibleCheckTypeHelper;
 use PHPStan\ShouldNotHappenException;
 use PHPStan\Turbo\ShadowedByTurboExtension;
 use PHPStan\Type\Accessory\HasPropertyType;
 use PHPStan\Type\Accessory\NonEmptyArrayType;
+use PHPStan\Type\CallableType;
+use PHPStan\Type\ClosureType;
 use PHPStan\Type\Constant\ConstantBooleanType;
 use PHPStan\Type\DynamicFunctionThrowTypeExtension;
 use PHPStan\Type\DynamicReturnTypeExtensionRegistry;
 use PHPStan\Type\ErrorType;
 use PHPStan\Type\Generic\TemplateTypeHelper;
 use PHPStan\Type\Generic\TemplateTypeVariance;
 use PHPStan\Type\Generic\TemplateTypeVarianceMap;
+use PHPStan\Type\MixedType;
 use PHPStan\Type\NeverType;
 use PHPStan\Type\ObjectType;
 use PHPStan\Type\Type;
@@ -112,6 +118,7 @@ public function __construct(
 		private ArgumentsHandler $argumentsHandler,
 		private ClosureProcessor $closureProcessor,
 		private AssignHandler $assignHandler,
+		private ClosureSignatureInference $closureSignatureInference,
 	)
 	{
 	}
@@ -341,6 +348,17 @@ public function processExpr(NodeScopeResolver $nodeScopeResolver, Stmt $stmt, Ex
 			}
 		}
 		$resolvedParametersAcceptor = $argsResult->getResolvedParametersAcceptor();
+		if (
+			$resolvedParametersAcceptor !== null
+			&& $nameResult !== null
+			&& $expr->name instanceof Expr\Variable
+			&& is_string($expr->name->name)
+		) {
+			$invokedClosureType = $this->resolveInvokedClosureType($nodeScopeResolver, $normalizedExpr, $expr->name->name, $nameResult->getType(), $argsResult->getScope(), $storage);
+			if ($invokedClosureType !== null) {
+				$resolvedParametersAcceptor = $invokedClosureType->getCallableParametersAcceptors($scope)[0];
+			}
+		}
 		// arguments walked ahead of the callee: the scope already carries them
 		// and the callee walk's own effects (a closure's by-ref uses) on top
 		if ($argumentsWalkedAhead === null) {
@@ -764,6 +782,63 @@ private function resolveReturnType(NodeScopeResolver $nodeScopeResolver, Mutatin
 		return TemplateArgumentFrame::returnTypeOfCall($parametersAcceptor, $reflectionScope, $expr);
 	}
 
+	/**
+	 * A closure whose signature is inferred from its invocations (see
+	 * ClosureSignatureInference) joins the arguments of all of them; invoked
+	 * with narrower ones, it returns what its body returns for these. The
+	 * variable holds the closure it was assigned when the type it holds is the
+	 * type the closure was created with.
+	 */
+	private function resolveInvokedClosureType(NodeScopeResolver $nodeScopeResolver, FuncCall $call, string $name, Type $calleeType, MutatingScope $scope, ExpressionResultStorage $storage): ?ClosureType
+	{
+		if (!$calleeType instanceof ClosureType || !$this->closureSignatureInference->infersInvocationReturnType($scope, $calleeType)) {
+			return null;
+		}
+		$parameters = $calleeType->getParameters();
+		$args = $call->getArgs();
+		if ($args === [] || count($args) > count($parameters)) {
+			return null;
+		}
+
+		$narrower = false;
+		$callableParameters = [];
+		foreach ($parameters as $i => $parameter) {
+			if ($parameter->isVariadic() || !$parameter->passedByReference()->no()) {
+				return null;
+			}
+			$type = $parameter->getType();
+			if (isset($args[$i])) {
+				if ($args[$i]->name !== null || $args[$i]->unpack) {
+					return null;
+				}
+				$argumentType = $nodeScopeResolver->readTypeOfMaybeStored($args[$i]->value, $scope);
+				// an argument the signature rejects is reported against it
+				if (!$type->isSuperTypeOf($argumentType)->yes()) {
+					return null;
+				}
+				if (!$argumentType->isSuperTypeOf($type)->yes()) {
+					$narrower = true;
+					$type = $argumentType;
+				}
+			}
+			$callableParameters[] = new NativeParameterReflection($parameter->getName(), $parameter->isOptional(), $type, PassedByReference::createNo(), false, null);
+		}
+		if (!$narrower) {
+			return null;
+		}
+
+		foreach ($this->closureSignatureInference->findAssignedClosures($scope, $name) as $closure) {
+			$creationResult = $storage->findExpressionResult($closure);
+			if ($creationResult === null || !$creationResult->getType()->equals($calleeType)) {
+				continue;
+			}
+
+			return $this->closureTypeResolver->getClosureType($creationResult->getBeforeScope(), $closure, false, $storage, new CallableType($callableParameters, new MixedType(), false));
+		}
+
+		return null;
+	}
+
 	/**
 	 * Ported inside-out from the old TypeResolvingExprHandler::specifyTypes(): the
 	 * FunctionTypeSpecifyingExtensions, conditional-return-type and @phpstan-assert

src/Analyser/ExprHandler/Helper/ClosureTypeResolver.php

@@ -120,15 +120,19 @@ private function findCachedTypes(Node\Expr\Closure|ArrowFunction $expr): array
 	 * the closure-as-call-arg store sites) feed the gathered returns/yields to
 	 * buildClosureType() instead, which constructs the same ClosureType without
 	 * a second walk.
+	 *
+	 * $passedToType types the parameters like a callable parameter the closure
+	 * is passed to does - FuncCallHandler passes the arguments of an invocation.
 	 */
 	public function getClosureType(
 		MutatingScope $scope,
 		Node\Expr\Closure|ArrowFunction $expr,
 		bool $shallow = false,
 		?ExpressionResultStorage $storage = null,
+		?Type $passedToType = null,
 	): ClosureType
 	{
-		[$parameters, $isVariadic, $callableParameters, $nativeCallableParameters, $contextFree] = $this->buildParametersAndAcceptors($scope, $expr, $storage);
+		[$parameters, $isVariadic, $callableParameters, $nativeCallableParameters, $contextFree] = $this->buildParametersAndAcceptors($scope, $expr, $storage, $passedToType);
 
 		// A shallow reflection is the closure/arrow function's signature without
 		// walking its body: parameters plus the DECLARED return type. Used at scope

src/Analyser/Generics/ClosureSignatureInference.php

@@ -12,12 +12,14 @@
 use PHPStan\Reflection\Native\NativeParameterReflection;
 use PHPStan\Reflection\PassedByReference;
 use PHPStan\Turbo\ShadowedByTurboExtension;
+use PHPStan\Type\ClosureType;
 use PHPStan\Type\Generic\TemplateTypeFactory;
 use PHPStan\Type\Generic\TemplateTypeScope;
 use PHPStan\Type\Generic\TemplateTypeVariance;
 use PHPStan\Type\Generic\UnresolvedTemplateArgumentType;
 use PHPStan\Type\MixedType;
 use PHPStan\Type\Type;
+use PHPStan\Type\TypeTraverser;
 use function array_keys;
 use function array_pop;
 use function count;
@@ -55,6 +57,8 @@ final class ClosureSignatureInference
 
 	private const CLOSED_BODY_ATTRIBUTE = 'closureSignatureClosedBody';
 
+	private const ASSIGNED_CLOSURES_ATTRIBUTE = 'closureSignatureAssignedClosures';
+
 	public function __construct(
 		#[AutowiredParameter(ref: '%featureToggles.closureSignaturesFromUsages%')]
 		private bool $enabled,
@@ -454,6 +458,103 @@ private static function scanClosedBody(Node $functionLike, array $stmts): bool
 		return true;
 	}
 
+	/**
+	 * Whether an invocation of the closure returns what the body returns for
+	 * its arguments (see FuncCallHandler): its signature is resolved - a body
+	 * walked once, with no sites of its own, invokes the resolved closures of
+	 * the body it is written in.
+	 */
+	public function infersInvocationReturnType(MutatingScope $scope, ClosureType $closureType): bool
+	{
+		if (!$this->enabled || $scope->getCurrentTemplateArgumentFrame() === null) {
+			return false;
+		}
+
+		$containsMarker = false;
+		TypeTraverser::map($closureType, static function (Type $type, callable $traverse) use (&$containsMarker): Type {
+			if ($type instanceof UnresolvedTemplateArgumentType) {
+				$containsMarker = true;
+			}
+
+			return $containsMarker ? $type : $traverse($type);
+		});
+
+		return !$containsMarker;
+	}
+
+	/**
+	 * The closures and arrow functions assigned to the local variable in the
+	 * body being walked and - a variable a closure captures - in the bodies
+	 * enclosing it.
+	 *
+	 * @return list<Closure|ArrowFunction>
+	 */
+	public function findAssignedClosures(MutatingScope $scope, string $name): array
+	{
+		if (!$this->enabled) {
+			return [];
+		}
+
+		$closures = [];
+		for ($frame = $scope->getCurrentTemplateArgumentFrame(); $frame !== null; $frame = $frame->getParent()) {
+			$body = $frame->getClosureSignatureBody();
+			if ($body === null) {
+				continue;
+			}
+			foreach (self::getAssignedClosures($body, $frame->getClosureSignatureStmts())[$name] ?? [] as $closure) {
+				$closures[] = $closure;
+			}
+		}
+
+		return $closures;
+	}
+
+	/**
+	 * @param Node\Stmt[] $stmts
+	 * @return array<string, list<Closure|ArrowFunction>>
+	 */
+	private static function getAssignedClosures(Node $body, array $stmts): array
+	{
+		/** @var array<string, list<Closure|ArrowFunction>>|null $cached */
+		$cached = $body->getAttribute(self::ASSIGNED_CLOSURES_ATTRIBUTE);
+		if ($cached !== null) {
+			return $cached;
+		}
+
+		$assigned = [];
+		$stack = $stmts;
+		while (count($stack) > 0) {
+			$node = array_pop($stack);
+			if ($node instanceof Node\FunctionLike || $node instanceof Node\Stmt\ClassLike) {
+				continue;
+			}
+			if (
+				$node instanceof Expr\Assign
+				&& $node->var instanceof Expr\Variable
+				&& is_string($node->var->name)
+				&& ($node->expr instanceof Closure || $node->expr instanceof ArrowFunction)
+			) {
+				$assigned[$node->var->name][] = $node->expr;
+			}
+			foreach ($node->getSubNodeNames() as $subNodeName) {
+				$subNode = $node->$subNodeName;
+				if ($subNode instanceof Node) {
+					$stack[] = $subNode;
+				} elseif (is_array($subNode)) {
+					foreach ($subNode as $item) {
+						if (!$item instanceof Node) {
+							continue;
+						}
+						$stack[] = $item;
+					}
+				}
+			}
+		}
+		$body->setAttribute(self::ASSIGNED_CLOSURES_ATTRIBUTE, $assigned);
+
+		return $assigned;
+	}
+
 	/**
 	 * @param array<string, true> $names
 	 */

src/Analyser/Generics/TemplateArgumentFrame.php

@@ -111,6 +111,12 @@ public function isSettledClosureSite(Expr $site): bool
 		return $this->parent !== null && $this->parent->isSettledClosureSite($site);
 	}
 
+	/** The frame of the body this frame's body is written in. */
+	public function getParent(): ?self
+	{
+		return $this->parent;
+	}
+
 	/**
 	 * The function-like body the frame observes, asked only when a closure in
 	 * it has its signature inferred (see ClosureSignatureInference::isClosedBody()).

src/Analyser/Generics/TemplateArgumentResolver.php

@@ -64,7 +64,7 @@ public function resolve(TemplateArgumentConstraints $constraints, ?TemplateArgum
 			TemplateArgumentStats::increment('closureSitesSettled', count($settledClosureSites));
 		}
 
-		return new TemplateArgumentFrame($parent, $resolutions, $this->collectSiteStatementIndexes($siteIndexes, $settledClosureSites), settledClosureSites: $settledClosureSites);
+		return new TemplateArgumentFrame($parent, $resolutions, $this->collectSiteStatementIndexes($siteIndexes, $settledClosureSites), $closureSignatureBody, $closureSignatureStmts, $settledClosureSites);
 	}
 
 	/**

tests/PHPStan/Analyser/nsrt/closure-signature-from-usages-generics.php

@@ -139,8 +139,8 @@ public function closureCreatesGenericObject(): void
 			assertType("1|'a'", $v);
 			return new Box($v);
 		};
-		assertType("ClosureSignatureFromUsagesGenerics\Box<1|'a'>", $make(1));
-		assertType("ClosureSignatureFromUsagesGenerics\Box<1|'a'>", $make('a'));
+		assertType('ClosureSignatureFromUsagesGenerics\Box<1>', $make(1));
+		assertType("ClosureSignatureFromUsagesGenerics\Box<'a'>", $make('a'));
 	}
 
 	public function closureFeedsGenericObject(): void

tests/PHPStan/Analyser/nsrt/closure-signature-from-usages.php

@@ -38,6 +38,26 @@ function takesMixed(mixed $m): void
 {
 }
 
+class InvokedCountry
+{
+
+	public static function tryFrom(mixed $value): ?self
+	{
+		return null;
+	}
+
+}
+
+class InvokedRegion
+{
+
+	public static function tryFrom(mixed $value): ?self
+	{
+		return null;
+	}
+
+}
+
 /**
  * @template T of \BackedEnum|int|string
  * @param \Closure(T): string $cb
@@ -100,7 +120,7 @@ public function arrowFunction(): void
 	{
 		$f = fn ($a) => $a;
 		$f(1);
-		assertType("1|'x'", $f('x'));
+		assertType("'x'", $f('x'));
 	}
 
 	public function arrayOffsets(): void
@@ -515,4 +535,35 @@ public function variadicParameterKeepsDeclaredType(): void
 		$outer('x', 1.0);
 	}
 
+	public function invocationReturnsWhatTheBodyReturnsForItsArguments(mixed $a, mixed $b): void
+	{
+		$toEnumList = static function (mixed $value, string $enumClassName): array {
+			assertType("'ClosureSignatureFromUsages\\\\InvokedCountry'|'ClosureSignatureFromUsages\\\\InvokedRegion'", $enumClassName);
+			$enumValues = [];
+			foreach ((array) $value as $val) {
+				$enumValue = $enumClassName::tryFrom($val);
+				if ($enumValue !== null) {
+					$enumValues[] = $enumValue;
+				}
+			}
+			return $enumValues;
+		};
+		assertType('list<ClosureSignatureFromUsages\\InvokedCountry>', $toEnumList($a, InvokedCountry::class));
+		assertType('list<ClosureSignatureFromUsages\\InvokedRegion>', $toEnumList($b, InvokedRegion::class));
+
+		$inner = static function (mixed $value) use ($toEnumList): void {
+			assertType('array{}|array{ClosureSignatureFromUsages\\InvokedCountry}', $toEnumList($value, InvokedCountry::class));
+		};
+		$inner(1);
+	}
+
+	public function invocationOfAReassignedVariable(): void
+	{
+		$f = static fn (int|string $x): int|string => $x;
+		assertType('1', $f(1));
+		$f = static fn (int|string $x): string => 'other';
+		assertType("'other'", $f(1));
+		$f('a');
+	}
+
 }