Improve consistency

Author: Richard van Velzen

src/Analyser/NodeScopeResolver.php

@@ -4115,7 +4115,7 @@ public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $n
 			$acceptsNamedArguments = $resolvedPhpDoc->acceptsNamedArguments();
 			$isReadOnly = $isReadOnly || $resolvedPhpDoc->isReadOnly();
 			$asserts = Assertions::createFromResolvedPhpDocBlock($resolvedPhpDoc);
-			$selfOutType = $resolvedPhpDoc->getThisOutTag() !== null ? $resolvedPhpDoc->getThisOutTag()->getType() : null;
+			$selfOutType = $resolvedPhpDoc->getSelfOutTag() !== null ? $resolvedPhpDoc->getSelfOutTag()->getType() : null;
 		}
 
 		return [$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, $isReadOnly, $docComment, $asserts, $selfOutType];

src/PhpDoc/ResolvedPhpDocBlock.php

@@ -220,7 +220,7 @@ public function merge(array $parents, array $parentPhpDocBlocks): self
 		$result->typeAliasTags = $this->getTypeAliasTags();
 		$result->typeAliasImportTags = $this->getTypeAliasImportTags();
 		$result->assertTags = self::mergeAssertTags($this->getAssertTags(), $parents, $parentPhpDocBlocks);
-		$result->selfOutTypeTag = $this->getThisOutTag();
+		$result->selfOutTypeTag = self::mergeSelfOutTypeTags($this->getSelfOutTag(), $parents);
 		$result->deprecatedTag = self::mergeDeprecatedTags($this->getDeprecatedTag(), $parents);
 		$result->isDeprecated = $result->deprecatedTag !== null;
 		$result->isInternal = $this->isInternal();
@@ -302,7 +302,7 @@ public function changeParameterNamesByMapping(array $parameterNameMapping): self
 		$self->typeAliasTags = $this->typeAliasTags;
 		$self->typeAliasImportTags = $this->typeAliasImportTags;
 		$self->assertTags = $assertTags;
-		$self->selfOutTypeTag = $this->getThisOutTag();
+		$self->selfOutTypeTag = $this->selfOutTypeTag;
 		$self->deprecatedTag = $this->deprecatedTag;
 		$self->isDeprecated = $this->isDeprecated;
 		$self->isInternal = $this->isInternal;
@@ -528,7 +528,7 @@ public function getAssertTags(): array
 		return $this->assertTags;
 	}
 
-	public function getThisOutTag(): ?SelfOutTypeTag
+	public function getSelfOutTag(): ?SelfOutTypeTag
 	{
 		if ($this->selfOutTypeTag === false) {
 			$this->selfOutTypeTag = $this->phpDocNodeResolver->resolveSelfOutTypeTag(
@@ -811,6 +811,25 @@ private static function mergeAssertTags(array $assertTags, array $parents, array
 		return $assertTags;
 	}
 
+	/**
+	 * @param array<int, self> $parents
+	 */
+	private static function mergeSelfOutTypeTags(?SelfOutTypeTag $selfOutTypeTag, array $parents): ?SelfOutTypeTag
+	{
+		if ($selfOutTypeTag !== null) {
+			return $selfOutTypeTag;
+		}
+		foreach ($parents as $parent) {
+			$result = $parent->getSelfOutTag();
+			if ($result === null) {
+				continue;
+			}
+			return $result;
+		}
+
+		return null;
+	}
+
 	/**
 	 * @param array<int, self> $parents
 	 */

src/Reflection/Php/PhpClassReflectionExtension.php

@@ -546,7 +546,7 @@ private function createMethod(
 
 						$asserts = Assertions::createFromResolvedPhpDocBlock($stubPhpDoc);
 
-						$selfOutTypeTag = $stubPhpDoc->getThisOutTag();
+						$selfOutTypeTag = $stubPhpDoc->getSelfOutTag();
 						if ($selfOutTypeTag !== null) {
 							$selfOutType = $selfOutTypeTag->getType();
 						}
@@ -575,7 +575,7 @@ private function createMethod(
 						}
 						$asserts = Assertions::createFromResolvedPhpDocBlock($phpDocBlock);
 
-						$selfOutTypeTag = $phpDocBlock->getThisOutTag();
+						$selfOutTypeTag = $phpDocBlock->getSelfOutTag();
 						if ($selfOutTypeTag !== null) {
 							$selfOutType = $selfOutTypeTag->getType();
 						}
@@ -727,7 +727,7 @@ private function createMethod(
 		$isFinal = $resolvedPhpDoc->isFinal();
 		$isPure = $resolvedPhpDoc->isPure();
 		$asserts = Assertions::createFromResolvedPhpDocBlock($resolvedPhpDoc);
-		$selfOutType = $resolvedPhpDoc->getThisOutTag() !== null ? $resolvedPhpDoc->getThisOutTag()->getType() : null;
+		$selfOutType = $resolvedPhpDoc->getSelfOutTag() !== null ? $resolvedPhpDoc->getSelfOutTag()->getType() : null;
 
 		return $this->methodReflectionFactory->create(
 			$declaringClass,

src/Rules/PhpDoc/IncompatibleSelfOutTypeRule.php

@@ -26,21 +26,24 @@ public function processNode(Node $node, Scope $scope): array
 	{
 		$method = $node->getMethodReflection();
 		$selfOutType = $method->getSelfOutType();
+
 		if ($selfOutType === null) {
 			return [];
 		}
 
 		$classReflection = $method->getDeclaringClass();
 		$classType = new ObjectType($classReflection->getName(), null, $classReflection);
 
-		if (!$classType->isSuperTypeOf($selfOutType)->no()) {
+		if ($classType->isSuperTypeOf($selfOutType)->yes()) {
 			return [];
 		}
 
 		return [
 			RuleErrorBuilder::message(sprintf(
-				'Out type %s is not compatible with %s.',
+				'Self-out type %s of method %s::%s is not subtype of %s.',
 				$selfOutType->describe(VerbosityLevel::precise()),
+				$classReflection->getName(),
+				$method->getName(),
 				$classType->describe(VerbosityLevel::precise()),
 			))->build(),
 		];

src/Rules/PhpDoc/InvalidPHPStanDocTagRule.php

@@ -44,6 +44,8 @@ class InvalidPHPStanDocTagRule implements Rule
 		'@phpstan-assert',
 		'@phpstan-assert-if-true',
 		'@phpstan-assert-if-false',
+		'@phpstan-self-out',
+		'@phpstan-this-out',
 	];
 
 	public function __construct(private Lexer $phpDocLexer, private PhpDocParser $phpDocParser)

tests/PHPStan/Analyser/data/self-out.php

@@ -52,6 +52,19 @@ public function test(): void {
     }
 }
 
+/**
+ * @template T
+ * @extends a<T>
+ */
+class b extends a {
+	/**
+	 * @param T $data
+	 */
+	public function __construct($data) {
+		parent::__construct($data);
+	}
+}
+
 function () {
 	$i = new a(123);
 	// OK - $i is a<123>
@@ -68,3 +81,11 @@ function () {
 	assertType('SelfOut\\a<string>', $i);
 	assertType('*NEVER*', $i->test());
 };
+
+function () {
+	$i = new b(123);
+	assertType('SelfOut\\b<int>', $i);
+
+	$i->addData(321);
+	assertType('SelfOut\\a<int>', $i);
+};

tests/PHPStan/Rules/PhpDoc/IncompatibleSelfOutTypeRuleTest.php

@@ -20,9 +20,13 @@ public function testRule(): void
 	{
 		$this->analyse([__DIR__ . '/data/incompatible-self-out-type.php'], [
 			[
-				'Out type int is not compatible with IncompatibleSelfOutType\A.',
+				'Self-out type int of method IncompatibleSelfOutType\A::three is not subtype of IncompatibleSelfOutType\A.',
 				23,
 			],
+			[
+				'Self-out type IncompatibleSelfOutType\A|null of method IncompatibleSelfOutType\A::four is not subtype of IncompatibleSelfOutType\A.',
+				28,
+			],
 		]);
 	}
 

tests/PHPStan/Rules/PhpDoc/data/incompatible-self-out-type.php

@@ -21,4 +21,9 @@ public function two($param);
 	 * @phpstan-self-out int
 	 */
 	public function three();
+
+	/**
+	 * @phpstan-self-out self|null
+	 */
+	public function four();
 }