Allow Traversable in PHPDoc and Iterator in native type to cooperate

Author: ondrejmirtes

phpstan-baseline.neon

@@ -1854,6 +1854,12 @@ parameters:
 			count: 1
 			path: src/Type/TypehintHelper.php
 
+		-
+			message: '#^Doing instanceof PHPStan\\Type\\TypeWithClassName is error\-prone and deprecated\. Use Type\:\:getObjectClassNames\(\) or Type\:\:getObjectClassReflections\(\) instead\.$#'
+			identifier: phpstanApi.instanceofType
+			count: 1
+			path: src/Type/TypehintHelper.php
+
 		-
 			message: '#^Doing instanceof PHPStan\\Type\\CallableType is error\-prone and deprecated\. Use Type\:\:isCallable\(\) and Type\:\:getCallableParametersAcceptors\(\) instead\.$#'
 			identifier: phpstanApi.instanceofType

src/Type/TypehintHelper.php

@@ -12,6 +12,7 @@
 use PHPStan\Type\Constant\ConstantArrayType;
 use PHPStan\Type\Generic\TemplateTypeHelper;
 use ReflectionType;
+use Traversable;
 use function array_map;
 use function count;
 use function get_class;
@@ -118,9 +119,24 @@ public static function decideType(
 				}
 			}
 
+			$resolvedPhpDocTypeToBounds = TemplateTypeHelper::resolveToBounds($phpDocType);
+			$isSuperType = $type->isSuperTypeOf($resolvedPhpDocTypeToBounds);
+			if (
+				!$isSuperType->yes()
+				&& (new ObjectType(Traversable::class))->isSuperTypeOf($phpDocType)->yes()
+				&& $type instanceof TypeWithClassName
+			) {
+				// if native type is Iterator and PHPDoc type is Traversable
+				// Allow PHPDoc type to win
+				$traversableAncestor = $type->getAncestorWithClassName(Traversable::class);
+				if ($traversableAncestor !== null) {
+					$isSuperType = $traversableAncestor->isSuperTypeOf($resolvedPhpDocTypeToBounds);
+				}
+			}
+
 			if (
 				(!$phpDocType instanceof NeverType || ($type instanceof MixedType && !$type->isExplicitMixed()))
-				&& $type->isSuperTypeOf(TemplateTypeHelper::resolveToBounds($phpDocType))->yes()
+				&& $isSuperType->yes()
 			) {
 				$resultType = $phpDocType;
 			} else {