ResolvedPhpDocBlock: fix parent return tag merging

build/baseline-7.4.neon

@@ -51,6 +51,12 @@ parameters:
 			message: "#^Class PHPStan\\\\PhpDoc\\\\ResolvedPhpDocBlock has an uninitialized property \\$phpDocNodeResolver\\. Give it default value or assign it in the constructor\\.$#"
 			count: 1
 			path: ../src/PhpDoc/ResolvedPhpDocBlock.php
+
+		-
+			message: "#^Class PHPStan\\\\PhpDoc\\\\ResolvedPhpDocBlock has an uninitialized property \\$reflectionProvider\\. Give it default value or assign it in the constructor\\.$#"
+			count: 1
+			path: ../src/PhpDoc/ResolvedPhpDocBlock.php
+
 		-
 			message: "#^Class PHPStan\\\\Reflection\\\\BetterReflection\\\\SourceLocator\\\\CachingVisitor has an uninitialized property \\$fileName\\. Give it default value or assign it in the constructor\\.$#"
 			count: 1

src/PhpDoc/ResolvedPhpDocBlock.php

@@ -22,10 +22,13 @@
 use PHPStan\PhpDoc\Tag\UsesTag;
 use PHPStan\PhpDoc\Tag\VarTag;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\ReflectionProvider;
 use PHPStan\Type\ConditionalTypeForParameter;
 use PHPStan\Type\Generic\TemplateTypeHelper;
 use PHPStan\Type\Generic\TemplateTypeMap;
 use PHPStan\Type\Generic\TemplateTypeVariance;
+use PHPStan\Type\StaticType;
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeTraverser;
 use function array_key_exists;
@@ -58,6 +61,8 @@ class ResolvedPhpDocBlock
 
 	private PhpDocNodeResolver $phpDocNodeResolver;
 
+	private ReflectionProvider $reflectionProvider;
+
 	/** @var array<(string|int), VarTag>|false */
 	private array|false $varTags = false;
 
@@ -138,6 +143,7 @@ public static function create(
 		TemplateTypeMap $templateTypeMap,
 		array $templateTags,
 		PhpDocNodeResolver $phpDocNodeResolver,
+		ReflectionProvider $reflectionProvider,
 	): self
 	{
 		// new property also needs to be added to createEmpty() and merge()
@@ -150,6 +156,7 @@ public static function create(
 		$self->templateTypeMap = $templateTypeMap;
 		$self->templateTags = $templateTags;
 		$self->phpDocNodeResolver = $phpDocNodeResolver;
+		$self->reflectionProvider = $reflectionProvider;
 
 		return $self;
 	}
@@ -199,6 +206,11 @@ public static function createEmpty(): self
 	 */
 	public function merge(array $parents, array $parentPhpDocBlocks): self
 	{
+		$className = $this->nameScope !== null ? $this->nameScope->getClassName() : null;
+		$classReflection = $className !== null && $this->reflectionProvider->hasClass($className)
+			? $this->reflectionProvider->getClass($className)
+			: null;
+
 		// new property also needs to be added to createEmpty()
 		$result = new self();
 		// we will resolve everything on $this here so these properties don't have to be populated
@@ -226,7 +238,7 @@ public function merge(array $parents, array $parentPhpDocBlocks): self
 		$result->usesTags = $this->getUsesTags();
 		$result->paramTags = self::mergeParamTags($this->getParamTags(), $parents, $parentPhpDocBlocks);
 		$result->paramOutTags = self::mergeParamOutTags($this->getParamOutTags(), $parents, $parentPhpDocBlocks);
-		$result->returnTag = self::mergeReturnTags($this->getReturnTag(), $parents, $parentPhpDocBlocks);
+		$result->returnTag = self::mergeReturnTags($this->getReturnTag(), $classReflection, $parents, $parentPhpDocBlocks);
 		$result->throwsTag = self::mergeThrowsTags($this->getThrowsTag(), $parents);
 		$result->mixinTags = $this->getMixinTags();
 		$result->typeAliasTags = $this->getTypeAliasTags();
@@ -312,6 +324,7 @@ public function changeParameterNamesByMapping(array $parameterNameMapping): self
 		$self->templateTypeMap = $this->templateTypeMap;
 		$self->templateTags = $this->templateTags;
 		$self->phpDocNodeResolver = $this->phpDocNodeResolver;
+		$self->reflectionProvider = $this->reflectionProvider;
 		$self->varTags = $this->varTags;
 		$self->methodTags = $this->methodTags;
 		$self->propertyTags = $this->propertyTags;
@@ -797,14 +810,14 @@ private static function mergeOneParentParamTags(array $paramTags, self $parent,
 	 * @param array<int, PhpDocBlock> $parentPhpDocBlocks
 	 * @return ReturnTag|Null
 	 */
-	private static function mergeReturnTags(?ReturnTag $returnTag, array $parents, array $parentPhpDocBlocks): ?ReturnTag
+	private static function mergeReturnTags(?ReturnTag $returnTag, ?ClassReflection $classReflection, array $parents, array $parentPhpDocBlocks): ?ReturnTag
 	{
 		if ($returnTag !== null) {
 			return $returnTag;
 		}
 
 		foreach ($parents as $i => $parent) {
-			$result = self::mergeOneParentReturnTag($returnTag, $parent, $parentPhpDocBlocks[$i]);
+			$result = self::mergeOneParentReturnTag($returnTag, $classReflection, $parent, $parentPhpDocBlocks[$i]);
 			if ($result === null) {
 				continue;
 			}
@@ -815,7 +828,7 @@ private static function mergeReturnTags(?ReturnTag $returnTag, array $parents, a
 		return null;
 	}
 
-	private static function mergeOneParentReturnTag(?ReturnTag $returnTag, self $parent, PhpDocBlock $phpDocBlock): ?ReturnTag
+	private static function mergeOneParentReturnTag(?ReturnTag $returnTag, ?ClassReflection $classReflection, self $parent, PhpDocBlock $phpDocBlock): ?ReturnTag
 	{
 		$parentReturnTag = $parent->getReturnTag();
 		if ($parentReturnTag === null) {
@@ -824,6 +837,21 @@ private static function mergeOneParentReturnTag(?ReturnTag $returnTag, self $par
 
 		$parentType = $parentReturnTag->getType();
 
+		if ($classReflection !== null) {
+			$parentType = TypeTraverser::map(
+				$parentType,
+				static function (Type $type, callable $traverse) use ($classReflection): Type {
+					if ($type instanceof StaticType) {
+						return $type->changeBaseClass($classReflection);
+					}
+
+					return $traverse($type);
+				},
+			);
+
+			$parentReturnTag = $parentReturnTag->withType($parentType);
+		}
+
 		// Each parent would overwrite the previous one except if it returns a less specific type.
 		// Do not care for incompatible types as there is a separate rule for that.
 		if ($returnTag !== null && $parentType->isSuperTypeOf($returnTag->getType())->yes()) {

src/Type/FileTypeMapper.php

@@ -159,6 +159,7 @@ private function createResolvedPhpDocBlock(string $phpDocKey, NameScope $nameSco
 			new TemplateTypeMap($phpDocTemplateTypes),
 			$templateTags,
 			$this->phpDocNodeResolver,
+			$this->reflectionProviderProvider->getReflectionProvider(),
 		);
 		$this->resolvedPhpDocBlockCacheCount++;
 

tests/PHPStan/Analyser/NodeScopeResolverTest.php

@@ -232,6 +232,7 @@ public function dataFileAsserts(): iterable
 		yield from $this->gatherAssertTypes(__DIR__ . '/data/bug-2378.php');
 		yield from $this->gatherAssertTypes(__DIR__ . '/data/bug-9985.php');
 		yield from $this->gatherAssertTypes(__DIR__ . '/data/bug-6294.php');
+		yield from $this->gatherAssertTypes(__DIR__ . '/data/bug-6462.php');
 		yield from $this->gatherAssertTypes(__DIR__ . '/data/bug-2580.php');
 		yield from $this->gatherAssertTypes(__DIR__ . '/data/bug-9753.php');
 

tests/PHPStan/Analyser/data/bug-6462.php

@@ -0,0 +1,57 @@
+<?php declare(strict_types = 1);
+
+namespace Bug6462;
+
+use function PHPStan\Testing\assertType;
+
+class Base
+{
+	/**
+	 * @return $this
+	 */
+	public function getThis(): self
+	{
+		return $this;
+	}
+}
+
+class Child extends Base
+{
+	/**
+	 * {@inheritDoc}
+	 */
+	public function getThis(): self
+	{
+		return $this;
+	}
+}
+
+class FixedChild extends Base
+{
+	/**
+	 * @return $this
+	 */
+	public function getThis(): self
+	{
+		return $this;
+	}
+}
+
+$base = new Base();
+$child = new Child();
+$fixedChild = new FixedChild();
+
+assertType('Bug6462\Base', $base->getThis());
+assertType('Bug6462\Child', $child->getThis());
+
+if ($base instanceof \Traversable) {
+	assertType('Bug6462\Base&Traversable', $base->getThis());
+}
+
+if ($child instanceof \Traversable) {
+	assertType('Bug6462\Child&Traversable', $child->getThis());
+}
+
+if ($fixedChild instanceof \Traversable) {
+	assertType('Bug6462\FixedChild&Traversable', $fixedChild->getThis());
+}

tests/PHPStan/Rules/Methods/data/method-signature.php

@@ -481,3 +481,19 @@ public function foobar(): array
 		];
 	}
 }
+
+abstract class SomeParent
+{
+	/**
+	 * @return $this
+	 */
+	abstract public function clear(): self;
+}
+
+class SomeChild extends SomeParent
+{
+	public function clear(): self
+	{
+		return $this;
+	}
+}