Narrow function return type to true/false based on @phpstan-assert-if-true/false

Instead of patching the optionality check in ArrayFilterFunctionReturnTypeHelper,
fix the root cause: when a function has @phpstan-assert-if-true annotations and
the argument types already satisfy the asserted type, narrow the return type from
bool to true (or false) at the FuncCallHandler level.

This makes $scope->getType(checkFoo($fooVar)) return true when checkFoo has
@phpstan-assert-if-true Foo $value and $fooVar is Foo, consistent with how
conditional return types (@return ($value is Foo ? true : false)) already work.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

src/Analyser/ExprHandler/FuncCallHandler.php

@@ -46,6 +46,7 @@
 use PHPStan\Type\ClosureType;
 use PHPStan\Type\Constant\ConstantArrayType;
 use PHPStan\Type\Constant\ConstantArrayTypeBuilder;
+use PHPStan\Type\Constant\ConstantBooleanType;
 use PHPStan\Type\ErrorType;
 use PHPStan\Type\GeneralizePrecision;
 use PHPStan\Type\IntegerRangeType;
@@ -70,6 +71,7 @@
 use function in_array;
 use function sprintf;
 use function str_starts_with;
+use function substr;
 
 /**
  * @implements ExprHandler<FuncCall>
@@ -817,7 +819,107 @@ public function resolveType(MutatingScope $scope, Expr $expr): Type
 			}
 		}
 
-		return VoidToNullTypeTransformer::transform($parametersAcceptor->getReturnType(), $expr);
+		$returnType = $parametersAcceptor->getReturnType();
+		$returnType = $this->narrowReturnTypeByAssertions($returnType, $functionReflection, $normalizedNode ?? $expr, $scope, $parametersAcceptor);
+
+		return VoidToNullTypeTransformer::transform($returnType, $expr);
+	}
+
+	private function narrowReturnTypeByAssertions(
+		Type $returnType,
+		FunctionReflection $functionReflection,
+		FuncCall $call,
+		MutatingScope $scope,
+		ParametersAcceptor $parametersAcceptor,
+	): Type
+	{
+		if (!$returnType->isBoolean()->yes() || $returnType->isTrue()->yes() || $returnType->isFalse()->yes()) {
+			return $returnType;
+		}
+
+		$assertions = $functionReflection->getAsserts();
+		$assertsIfFalse = $assertions->getAssertsIfFalse();
+		$assertsIfTrue = $assertions->getAssertsIfTrue();
+
+		if (count($assertsIfFalse) === 0 && count($assertsIfTrue) === 0) {
+			return $returnType;
+		}
+
+		$argTypes = $this->buildArgTypesForAssertions($call, $scope, $parametersAcceptor);
+
+		foreach ($assertsIfFalse as $assert) {
+			$param = $assert->getParameter();
+			if ($param->describe() !== $param->getParameterName()) {
+				continue;
+			}
+
+			$paramName = substr($param->getParameterName(), 1);
+			if (!isset($argTypes[$paramName])) {
+				continue;
+			}
+
+			$actualType = $argTypes[$paramName];
+			$assertedType = $assert->getType();
+
+			if ($assert->isNegated()) {
+				if ($assertedType->isSuperTypeOf($actualType)->yes()) {
+					return new ConstantBooleanType(true);
+				}
+			} else {
+				if ($assertedType->isSuperTypeOf($actualType)->no()) {
+					return new ConstantBooleanType(true);
+				}
+			}
+		}
+
+		foreach ($assertsIfTrue as $assert) {
+			$param = $assert->getParameter();
+			if ($param->describe() !== $param->getParameterName()) {
+				continue;
+			}
+
+			$paramName = substr($param->getParameterName(), 1);
+			if (!isset($argTypes[$paramName])) {
+				continue;
+			}
+
+			$actualType = $argTypes[$paramName];
+			$assertedType = $assert->getType();
+
+			if ($assert->isNegated()) {
+				if ($assertedType->isSuperTypeOf($actualType)->yes()) {
+					return new ConstantBooleanType(false);
+				}
+			} else {
+				if ($assertedType->isSuperTypeOf($actualType)->no()) {
+					return new ConstantBooleanType(false);
+				}
+			}
+		}
+
+		return $returnType;
+	}
+
+	/**
+	 * @return array<string, Type>
+	 */
+	private function buildArgTypesForAssertions(FuncCall $call, MutatingScope $scope, ParametersAcceptor $parametersAcceptor): array
+	{
+		$argTypes = [];
+		$parameters = $parametersAcceptor->getParameters();
+		foreach ($call->getArgs() as $i => $arg) {
+			$name = null;
+			if ($arg->name !== null) {
+				$name = $arg->name->toString();
+			} elseif (isset($parameters[$i])) {
+				$name = $parameters[$i]->getName();
+			}
+			if ($name !== null) {
+				$argTypes[$name] = $scope->getType($arg->value);
+			}
+		}
+
+		return $argTypes;
 	}
 
 	private function getDynamicFunctionReturnType(MutatingScope $scope, FuncCall $normalizedNode, FunctionReflection $functionReflection): ?Type

src/Type/Php/ArrayFilterFunctionReturnTypeHelper.php

@@ -260,22 +260,12 @@ private function processKeyAndItemType(MutatingScope $scope, Type $keyType, Type
 			return [new NeverType(), new NeverType(), false];
 		}
 
-		$truthyScope = $scope->filterByTruthyValue($expr);
-
-		$optional = !$booleanResult->isTrue()->yes();
-		if ($optional) {
-			$falseyScope = $scope->filterByFalseyValue($expr);
-			$falseyItemType = $itemVarName !== null ? $falseyScope->getVariableType($itemVarName) : $itemType;
-			$falseyKeyType = $keyVarName !== null ? $falseyScope->getVariableType($keyVarName) : $keyType;
-			if ($falseyItemType instanceof NeverType || $falseyKeyType instanceof NeverType) {
-				$optional = false;
-			}
-		}
+		$scope = $scope->filterByTruthyValue($expr);
 
 		return [
-			$keyVarName !== null ? $truthyScope->getVariableType($keyVarName) : $keyType,
-			$itemVarName !== null ? $truthyScope->getVariableType($itemVarName) : $itemType,
-			$optional,
+			$keyVarName !== null ? $scope->getVariableType($keyVarName) : $keyType,
+			$itemVarName !== null ? $scope->getVariableType($itemVarName) : $itemType,
+			!$booleanResult->isTrue()->yes(),
 		];
 	}