Merge branch 2.1.x into 2.2.x

phpstan-bot · phpstan-bot · commit 6aa6db5b3ec6 · 2026-04-05T09:55:58.000Z
diff --git a/src/Rules/PhpDoc/VarTagTypeRuleHelper.php b/src/Rules/PhpDoc/VarTagTypeRuleHelper.php
@@ -18,6 +18,7 @@
 use PHPStan\Type\ArrayType;
 use PHPStan\Type\FileTypeMapper;
 use PHPStan\Type\Generic\GenericObjectType;
+use PHPStan\Type\IsSuperTypeOfResult;
 use PHPStan\Type\MixedType;
 use PHPStan\Type\ObjectType;
 use PHPStan\Type\Type;
@@ -92,22 +93,25 @@ public function checkExprType(Scope $scope, Node\Expr $expr, Type $varTagType):
 		$errors = [];
 		$exprNativeType = $scope->getScopeNativeType($expr);
 		$containsPhpStanType = $this->containsPhpStanType($varTagType);
-		if ($this->shouldVarTagTypeBeReported($scope, $expr, $exprNativeType, $varTagType)) {
+
+		$isValidSuperTypeOfExpr = $this->isValidSuperTypeOfExpr($scope, $expr, $exprNativeType, $varTagType);
+		if (!$isValidSuperTypeOfExpr->yes()) {
 			$verbosity = VerbosityLevel::getRecommendedLevelByType($exprNativeType, $varTagType);
 			$errors[] = RuleErrorBuilder::message(sprintf(
 				'PHPDoc tag @var with type %s is not subtype of native type %s.',
 				$varTagType->describe($verbosity),
 				$exprNativeType->describe($verbosity),
-			))->identifier('varTag.nativeType')->build();
+			))->acceptsReasonsTip($isValidSuperTypeOfExpr->reasons)->identifier('varTag.nativeType')->build();
 		} elseif ($this->checkTypeAgainstPhpDocType || $containsPhpStanType) {
 			$exprType = $scope->getScopeType($expr);
-			if ($this->shouldVarTagTypeBeReported($scope, $expr, $exprType, $varTagType)) {
+			$isValidSuperTypeOfExpr = $this->isValidSuperTypeOfExpr($scope, $expr, $exprType, $varTagType);
+			if (!$isValidSuperTypeOfExpr->yes()) {
 				$verbosity = VerbosityLevel::getRecommendedLevelByType($exprType, $varTagType);
 				$errors[] = RuleErrorBuilder::message(sprintf(
 					'PHPDoc tag @var with type %s is not subtype of type %s.',
 					$varTagType->describe($verbosity),
 					$exprType->describe($verbosity),
-				))->identifier('varTag.type')->build();
+				))->acceptsReasonsTip($isValidSuperTypeOfExpr->reasons)->identifier('varTag.type')->build();
 			}
 		}
 
@@ -145,22 +149,22 @@ private function containsPhpStanType(Type $type): bool
 		return false;
 	}
 
-	private function shouldVarTagTypeBeReported(Scope $scope, Node\Expr $expr, Type $type, Type $varTagType): bool
+	private function isValidSuperTypeOfExpr(Scope $scope, Node\Expr $expr, Type $type, Type $varTagType): IsSuperTypeOfResult
 	{
 		if ($expr instanceof Expr\Array_) {
 			if ($expr->items === []) {
 				$type = new ArrayType(new MixedType(), new MixedType());
 			}
 
-			return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
+			return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
 		}
 
 		if ($expr instanceof Expr\ConstFetch) {
-			return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
+			return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
 		}
 
 		if ($expr instanceof Node\Scalar) {
-			return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
+			return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
 		}
 
 		if ($expr instanceof Expr\New_) {
@@ -169,72 +173,78 @@ private function shouldVarTagTypeBeReported(Scope $scope, Node\Expr $expr, Type
 			}
 		}
 
-		return $this->checkType($scope, $type, $varTagType);
+		return $this->isValidSuperType($scope, $type, $varTagType);
 	}
 
-	private function checkType(Scope $scope, Type $type, Type $varTagType, int $depth = 0): bool
+	private function isValidSuperType(Scope $scope, Type $type, Type $varTagType, int $depth = 0): IsSuperTypeOfResult
 	{
 		if ($this->strictWideningCheck) {
-			return !$this->isSuperTypeOfVarType($scope, $type, $varTagType);
+			return $this->isSuperTypeOfVarType($scope, $type, $varTagType);
 		}
 
 		if ($type->isConstantArray()->yes()) {
 			if ($type->isIterableAtLeastOnce()->no()) {
 				$type = new ArrayType(new MixedType(), new MixedType());
-				return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
+				return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
 			}
 		}
 
 		if ($type->isIterable()->yes() && $varTagType->isIterable()->yes()) {
-			if (!$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType)) {
-				return true;
+			$isAtLeastMaybeSuperTypeOf = $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
+			if ($isAtLeastMaybeSuperTypeOf->no()) {
+				return $isAtLeastMaybeSuperTypeOf;
 			}
 
 			$innerType = $type->getIterableValueType();
 			$innerVarTagType = $varTagType->getIterableValueType();
 
 			if ($type->equals($innerType) || $varTagType->equals($innerVarTagType)) {
-				return !$this->isSuperTypeOfVarType($scope, $innerType, $innerVarTagType);
+				return $this->isSuperTypeOfVarType($scope, $innerType, $innerVarTagType);
 			}
 
-			return $this->checkType($scope, $innerType, $innerVarTagType, $depth + 1);
+			return $this->isValidSuperType($scope, $innerType, $innerVarTagType, $depth + 1);
 		}
 
 		if ($depth === 0 && $type->isConstantValue()->yes()) {
-			return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
+			return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);
 		}
 
-		return !$this->isSuperTypeOfVarType($scope, $type, $varTagType);
+		return $this->isSuperTypeOfVarType($scope, $type, $varTagType);
 	}
 
-	private function isSuperTypeOfVarType(Scope $scope, Type $type, Type $varTagType): bool
+	private function isSuperTypeOfVarType(Scope $scope, Type $type, Type $varTagType): IsSuperTypeOfResult
 	{
 		if ($type->isSuperTypeOf($varTagType)->yes()) {
-			return true;
+			return IsSuperTypeOfResult::createYes();
 		}
 
 		try {
 			$type = $this->typeNodeResolver->resolve($type->toPhpDocNode(), $this->createNameScope($scope));
 		} catch (NameScopeAlreadyBeingCreatedException) {
-			return true;
+			return IsSuperTypeOfResult::createYes();
 		}
 
-		return $type->isSuperTypeOf($varTagType)->yes();
+		return $type->isSuperTypeOf($varTagType);
 	}
 
-	private function isAtLeastMaybeSuperTypeOfVarType(Scope $scope, Type $type, Type $varTagType): bool
+	private function isAtLeastMaybeSuperTypeOfVarType(Scope $scope, Type $type, Type $varTagType): IsSuperTypeOfResult
 	{
 		if (!$type->isSuperTypeOf($varTagType)->no()) {
-			return true;
+			return IsSuperTypeOfResult::createYes();
 		}
 
 		try {
 			$type = $this->typeNodeResolver->resolve($type->toPhpDocNode(), $this->createNameScope($scope));
 		} catch (NameScopeAlreadyBeingCreatedException) {
-			return true;
+			return IsSuperTypeOfResult::createYes();
+		}
+
+		$isSuperTypeOf = $type->isSuperTypeOf($varTagType);
+		if (!$isSuperTypeOf->no()) {
+			return IsSuperTypeOfResult::createYes();
 		}
 
-		return !$type->isSuperTypeOf($varTagType)->no();
+		return $isSuperTypeOf;
 	}
 
 	/**
diff --git a/tests/PHPStan/Rules/PhpDoc/WrongVariableNameInVarTagRuleTest.php b/tests/PHPStan/Rules/PhpDoc/WrongVariableNameInVarTagRuleTest.php
@@ -594,10 +594,12 @@ public function testGenericSubtype(): void
 			[
 				'PHPDoc tag @var with type GenericSubtype\IRepository<E of GenericSubtype\IEntity> is not subtype of type GenericSubtype\IRepository<GenericSubtype\IEntity>.',
 				78,
+				'Template type E on class GenericSubtype\IRepository is not covariant. Learn more: <fg=cyan>https://phpstan.org/blog/whats-up-with-template-covariant</>',
 			],
 			[
 				'PHPDoc tag @var with type GenericSubtype\IRepository<GenericSubtype\Foo> is not subtype of type GenericSubtype\IRepository<GenericSubtype\IEntity>.',
 				131,
+				'Template type E on class GenericSubtype\IRepository is not covariant. Learn more: <fg=cyan>https://phpstan.org/blog/whats-up-with-template-covariant</>',
 			],
 		]);
 	}

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@`
`18`	`18`	`use PHPStan\Type\ArrayType;`
`19`	`19`	`use PHPStan\Type\FileTypeMapper;`
`20`	`20`	`use PHPStan\Type\Generic\GenericObjectType;`
	`21`	`+use PHPStan\Type\IsSuperTypeOfResult;`
`21`	`22`	`use PHPStan\Type\MixedType;`
`22`	`23`	`use PHPStan\Type\ObjectType;`
`23`	`24`	`use PHPStan\Type\Type;`
`@@ -92,22 +93,25 @@ public function checkExprType(Scope $scope, Node\Expr $expr, Type $varTagType):`
`92`	`93`	`$errors = [];`
`93`	`94`	`$exprNativeType = $scope->getScopeNativeType($expr);`
`94`	`95`	`$containsPhpStanType = $this->containsPhpStanType($varTagType);`
`95`		`- if ($this->shouldVarTagTypeBeReported($scope, $expr, $exprNativeType, $varTagType)) {`
	`96`	`+`
	`97`	`+ $isValidSuperTypeOfExpr = $this->isValidSuperTypeOfExpr($scope, $expr, $exprNativeType, $varTagType);`
	`98`	`+ if (!$isValidSuperTypeOfExpr->yes()) {`
`96`	`99`	`$verbosity = VerbosityLevel::getRecommendedLevelByType($exprNativeType, $varTagType);`
`97`	`100`	`$errors[] = RuleErrorBuilder::message(sprintf(`
`98`	`101`	`'PHPDoc tag @var with type %s is not subtype of native type %s.',`
`99`	`102`	`$varTagType->describe($verbosity),`
`100`	`103`	`$exprNativeType->describe($verbosity),`
`101`		`- ))->identifier('varTag.nativeType')->build();`
	`104`	`+ ))->acceptsReasonsTip($isValidSuperTypeOfExpr->reasons)->identifier('varTag.nativeType')->build();`
`102`	`105`	`} elseif ($this->checkTypeAgainstPhpDocType \|\| $containsPhpStanType) {`
`103`	`106`	`$exprType = $scope->getScopeType($expr);`
`104`		`- if ($this->shouldVarTagTypeBeReported($scope, $expr, $exprType, $varTagType)) {`
	`107`	`+ $isValidSuperTypeOfExpr = $this->isValidSuperTypeOfExpr($scope, $expr, $exprType, $varTagType);`
	`108`	`+ if (!$isValidSuperTypeOfExpr->yes()) {`
`105`	`109`	`$verbosity = VerbosityLevel::getRecommendedLevelByType($exprType, $varTagType);`
`106`	`110`	`$errors[] = RuleErrorBuilder::message(sprintf(`
`107`	`111`	`'PHPDoc tag @var with type %s is not subtype of type %s.',`
`108`	`112`	`$varTagType->describe($verbosity),`
`109`	`113`	`$exprType->describe($verbosity),`
`110`		`- ))->identifier('varTag.type')->build();`
	`114`	`+ ))->acceptsReasonsTip($isValidSuperTypeOfExpr->reasons)->identifier('varTag.type')->build();`
`111`	`115`	`}`
`112`	`116`	`}`
`113`	`117`
`@@ -145,22 +149,22 @@ private function containsPhpStanType(Type $type): bool`
`145`	`149`	`return false;`
`146`	`150`	`}`
`147`	`151`
`148`		`- private function shouldVarTagTypeBeReported(Scope $scope, Node\Expr $expr, Type $type, Type $varTagType): bool`
	`152`	`+ private function isValidSuperTypeOfExpr(Scope $scope, Node\Expr $expr, Type $type, Type $varTagType): IsSuperTypeOfResult`
`149`	`153`	`{`
`150`	`154`	`if ($expr instanceof Expr\Array_) {`
`151`	`155`	`if ($expr->items === []) {`
`152`	`156`	`$type = new ArrayType(new MixedType(), new MixedType());`
`153`	`157`	`}`
`154`	`158`
`155`		`- return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
	`159`	`+ return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
`156`	`160`	`}`
`157`	`161`
`158`	`162`	`if ($expr instanceof Expr\ConstFetch) {`
`159`		`- return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
	`163`	`+ return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
`160`	`164`	`}`
`161`	`165`
`162`	`166`	`if ($expr instanceof Node\Scalar) {`
`163`		`- return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
	`167`	`+ return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
`164`	`168`	`}`
`165`	`169`
`166`	`170`	`if ($expr instanceof Expr\New_) {`
`@@ -169,72 +173,78 @@ private function shouldVarTagTypeBeReported(Scope $scope, Node\Expr $expr, Type`
`169`	`173`	`}`
`170`	`174`	`}`
`171`	`175`
`172`		`- return $this->checkType($scope, $type, $varTagType);`
	`176`	`+ return $this->isValidSuperType($scope, $type, $varTagType);`
`173`	`177`	`}`
`174`	`178`
`175`		`- private function checkType(Scope $scope, Type $type, Type $varTagType, int $depth = 0): bool`
	`179`	`+ private function isValidSuperType(Scope $scope, Type $type, Type $varTagType, int $depth = 0): IsSuperTypeOfResult`
`176`	`180`	`{`
`177`	`181`	`if ($this->strictWideningCheck) {`
`178`		`- return !$this->isSuperTypeOfVarType($scope, $type, $varTagType);`
	`182`	`+ return $this->isSuperTypeOfVarType($scope, $type, $varTagType);`
`179`	`183`	`}`
`180`	`184`
`181`	`185`	`if ($type->isConstantArray()->yes()) {`
`182`	`186`	`if ($type->isIterableAtLeastOnce()->no()) {`
`183`	`187`	`$type = new ArrayType(new MixedType(), new MixedType());`
`184`		`- return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
	`188`	`+ return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
`185`	`189`	`}`
`186`	`190`	`}`
`187`	`191`
`188`	`192`	`if ($type->isIterable()->yes() && $varTagType->isIterable()->yes()) {`
`189`		`- if (!$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType)) {`
`190`		`- return true;`
	`193`	`+ $isAtLeastMaybeSuperTypeOf = $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
	`194`	`+ if ($isAtLeastMaybeSuperTypeOf->no()) {`
	`195`	`+ return $isAtLeastMaybeSuperTypeOf;`
`191`	`196`	`}`
`192`	`197`
`193`	`198`	`$innerType = $type->getIterableValueType();`
`194`	`199`	`$innerVarTagType = $varTagType->getIterableValueType();`
`195`	`200`
`196`	`201`	`if ($type->equals($innerType) \|\| $varTagType->equals($innerVarTagType)) {`
`197`		`- return !$this->isSuperTypeOfVarType($scope, $innerType, $innerVarTagType);`
	`202`	`+ return $this->isSuperTypeOfVarType($scope, $innerType, $innerVarTagType);`
`198`	`203`	`}`
`199`	`204`
`200`		`- return $this->checkType($scope, $innerType, $innerVarTagType, $depth + 1);`
	`205`	`+ return $this->isValidSuperType($scope, $innerType, $innerVarTagType, $depth + 1);`
`201`	`206`	`}`
`202`	`207`
`203`	`208`	`if ($depth === 0 && $type->isConstantValue()->yes()) {`
`204`		`- return !$this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
	`209`	`+ return $this->isAtLeastMaybeSuperTypeOfVarType($scope, $type, $varTagType);`
`205`	`210`	`}`
`206`	`211`
`207`		`- return !$this->isSuperTypeOfVarType($scope, $type, $varTagType);`
	`212`	`+ return $this->isSuperTypeOfVarType($scope, $type, $varTagType);`
`208`	`213`	`}`
`209`	`214`
`210`		`- private function isSuperTypeOfVarType(Scope $scope, Type $type, Type $varTagType): bool`
	`215`	`+ private function isSuperTypeOfVarType(Scope $scope, Type $type, Type $varTagType): IsSuperTypeOfResult`
`211`	`216`	`{`
`212`	`217`	`if ($type->isSuperTypeOf($varTagType)->yes()) {`
`213`		`- return true;`
	`218`	`+ return IsSuperTypeOfResult::createYes();`
`214`	`219`	`}`
`215`	`220`
`216`	`221`	`try {`
`217`	`222`	`$type = $this->typeNodeResolver->resolve($type->toPhpDocNode(), $this->createNameScope($scope));`
`218`	`223`	`} catch (NameScopeAlreadyBeingCreatedException) {`
`219`		`- return true;`
	`224`	`+ return IsSuperTypeOfResult::createYes();`
`220`	`225`	`}`
`221`	`226`
`222`		`- return $type->isSuperTypeOf($varTagType)->yes();`
	`227`	`+ return $type->isSuperTypeOf($varTagType);`
`223`	`228`	`}`
`224`	`229`
`225`		`- private function isAtLeastMaybeSuperTypeOfVarType(Scope $scope, Type $type, Type $varTagType): bool`
	`230`	`+ private function isAtLeastMaybeSuperTypeOfVarType(Scope $scope, Type $type, Type $varTagType): IsSuperTypeOfResult`
`226`	`231`	`{`
`227`	`232`	`if (!$type->isSuperTypeOf($varTagType)->no()) {`
`228`		`- return true;`
	`233`	`+ return IsSuperTypeOfResult::createYes();`
`229`	`234`	`}`
`230`	`235`
`231`	`236`	`try {`
`232`	`237`	`$type = $this->typeNodeResolver->resolve($type->toPhpDocNode(), $this->createNameScope($scope));`
`233`	`238`	`} catch (NameScopeAlreadyBeingCreatedException) {`
`234`		`- return true;`
	`239`	`+ return IsSuperTypeOfResult::createYes();`
	`240`	`+ }`
	`241`	`+`
	`242`	`+ $isSuperTypeOf = $type->isSuperTypeOf($varTagType);`
	`243`	`+ if (!$isSuperTypeOf->no()) {`
	`244`	`+ return IsSuperTypeOfResult::createYes();`
`235`	`245`	`}`
`236`	`246`
`237`		`- return !$type->isSuperTypeOf($varTagType)->no();`
	`247`	`+ return $isSuperTypeOf;`
`238`	`248`	`}`
`239`	`249`
`240`	`250`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -594,10 +594,12 @@ public function testGenericSubtype(): void`
`594`	`594`	`[`
`595`	`595`	`'PHPDoc tag @var with type GenericSubtype\IRepository<E of GenericSubtype\IEntity> is not subtype of type GenericSubtype\IRepository<GenericSubtype\IEntity>.',`
`596`	`596`	`78,`
	`597`	`+ 'Template type E on class GenericSubtype\IRepository is not covariant. Learn more: <fg=cyan>https://phpstan.org/blog/whats-up-with-template-covariant</>',`
`597`	`598`	`],`
`598`	`599`	`[`
`599`	`600`	`'PHPDoc tag @var with type GenericSubtype\IRepository<GenericSubtype\Foo> is not subtype of type GenericSubtype\IRepository<GenericSubtype\IEntity>.',`
`600`	`601`	`131,`
	`602`	`+ 'Template type E on class GenericSubtype\IRepository is not covariant. Learn more: <fg=cyan>https://phpstan.org/blog/whats-up-with-template-covariant</>',`
`601`	`603`	`],`
`602`	`604`	`]);`
`603`	`605`	`}`