Add @phpstan-self-out support

conf/config.level2.neon

@@ -35,6 +35,7 @@ rules:
 	- PHPStan\Rules\PhpDoc\MethodConditionalReturnTypeRule
 	- PHPStan\Rules\PhpDoc\FunctionAssertRule
 	- PHPStan\Rules\PhpDoc\MethodAssertRule
+	- PHPStan\Rules\PhpDoc\IncompatibleSelfOutTypeRule
 	- PHPStan\Rules\PhpDoc\IncompatibleClassConstantPhpDocTypeRule
 	- PHPStan\Rules\PhpDoc\IncompatiblePhpDocTypeRule
 	- PHPStan\Rules\PhpDoc\IncompatiblePropertyPhpDocTypeRule

phpstan-baseline.neon

@@ -143,6 +143,11 @@ parameters:
 			count: 1
 			path: src/PhpDoc/PhpDocBlock.php
 
+		-
+			message: "#^Call to function method_exists\\(\\) with PHPStan\\\\PhpDocParser\\\\Ast\\\\PhpDoc\\\\PhpDocNode and 'getSelfOutTypeTagVa…' will always evaluate to true\\.$#"
+			count: 1
+			path: src/PhpDoc/PhpDocNodeResolver.php
+
 		-
 			message: "#^Method PHPStan\\\\PhpDoc\\\\ResolvedPhpDocBlock\\:\\:getNameScope\\(\\) should return PHPStan\\\\Analyser\\\\NameScope but returns PHPStan\\\\Analyser\\\\NameScope\\|null\\.$#"
 			count: 1
@@ -166,6 +171,11 @@ parameters:
 			count: 1
 			path: src/PhpDoc/Tag/ReturnTag.php
 
+		-
+			message: "#^Return type \\(PHPStan\\\\PhpDoc\\\\Tag\\\\SelfOutTypeTag\\) of method PHPStan\\\\PhpDoc\\\\Tag\\\\SelfOutTypeTag\\:\\:withType\\(\\) should be covariant with return type \\(static\\(PHPStan\\\\PhpDoc\\\\Tag\\\\TypedTag\\)\\) of method PHPStan\\\\PhpDoc\\\\Tag\\\\TypedTag\\:\\:withType\\(\\)$#"
+			count: 1
+			path: src/PhpDoc/Tag/SelfOutTypeTag.php
+
 		-
 			message: "#^Return type \\(PHPStan\\\\PhpDoc\\\\Tag\\\\VarTag\\) of method PHPStan\\\\PhpDoc\\\\Tag\\\\VarTag\\:\\:withType\\(\\) should be covariant with return type \\(static\\(PHPStan\\\\PhpDoc\\\\Tag\\\\TypedTag\\)\\) of method PHPStan\\\\PhpDoc\\\\Tag\\\\TypedTag\\:\\:withType\\(\\)$#"
 			count: 1

src/Analyser/MutatingScope.php

@@ -2532,6 +2532,7 @@ public function enterClassMethod(
 		?bool $isPure = null,
 		bool $acceptsNamedArguments = true,
 		?Assertions $asserts = null,
+		?Type $selfOutType = null,
 	): self
 	{
 		if (!$this->isInClass()) {
@@ -2557,6 +2558,7 @@ public function enterClassMethod(
 				$isPure,
 				$acceptsNamedArguments,
 				$asserts ?? Assertions::createEmpty(),
+				$selfOutType,
 			),
 			!$classMethod->isStatic(),
 		);

src/Analyser/NodeScopeResolver.php

@@ -107,6 +107,7 @@
 use PHPStan\PhpDoc\StubPhpDocProvider;
 use PHPStan\Reflection\Assertions;
 use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\ExtendedMethodReflection;
 use PHPStan\Reflection\FunctionReflection;
 use PHPStan\Reflection\InitializerExprTypeResolver;
 use PHPStan\Reflection\MethodReflection;
@@ -468,7 +469,7 @@ private function processStmtNode(
 			$hasYield = false;
 			$throwPoints = [];
 			$this->processAttributeGroups($stmt->attrGroups, $scope, $nodeCallback);
-			[$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, , , $asserts] = $this->getPhpDocs($scope, $stmt);
+			[$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, , , $asserts, $selfOutType] = $this->getPhpDocs($scope, $stmt);
 
 			foreach ($stmt->params as $param) {
 				$this->processParamNode($param, $scope, $nodeCallback);
@@ -491,6 +492,7 @@ private function processStmtNode(
 				$isPure,
 				$acceptsNamedArguments,
 				$asserts,
+				$selfOutType,
 			);
 
 			if ($stmt->name->toLowerString() === '__construct') {
@@ -526,7 +528,7 @@ private function processStmtNode(
 
 			if ($stmt->getAttribute('virtual', false) === false) {
 				$methodReflection = $methodScope->getFunction();
-				if (!$methodReflection instanceof MethodReflection) {
+				if (!$methodReflection instanceof ExtendedMethodReflection) {
 					throw new ShouldNotHappenException();
 				}
 				$nodeCallback(new InClassMethodNode($methodReflection, $stmt), $methodScope);
@@ -2063,6 +2065,13 @@ static function (?Type $offsetType, Type $valueType, bool $optional) use (&$arra
 						$scope = $scope->invalidateExpression($arg->value, true);
 					}
 				}
+
+				if ($parametersAcceptor !== null) {
+					$selfOutType = $methodReflection->getSelfOutType();
+					if ($selfOutType !== null) {
+						$scope = $scope->assignExpression($expr->var, TemplateTypeHelper::resolveTemplateTypes($selfOutType, $parametersAcceptor->getResolvedTemplateTypeMap()));
+					}
+				}
 			} else {
 				$throwPoints[] = ThrowPoint::createImplicit($scope, $expr);
 			}
@@ -3980,7 +3989,7 @@ private function processNodesForTraitUse($node, ClassReflection $traitReflection
 	}
 
 	/**
-	 * @return array{TemplateTypeMap, Type[], ?Type, ?Type, ?string, bool, bool, bool, bool|null, bool, bool, string|null, Assertions}
+	 * @return array{TemplateTypeMap, Type[], ?Type, ?Type, ?string, bool, bool, bool, bool|null, bool, bool, string|null, Assertions, ?Type}
 	 */
 	public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $node): array
 	{
@@ -3996,6 +4005,7 @@ public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $n
 		$acceptsNamedArguments = true;
 		$isReadOnly = $scope->isInClass() && $scope->getClassReflection()->isImmutable();
 		$asserts = Assertions::createEmpty();
+		$selfOutType = null;
 		$docComment = $node->getDocComment() !== null
 			? $node->getDocComment()->getText()
 			: null;
@@ -4105,9 +4115,10 @@ public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $n
 			$acceptsNamedArguments = $resolvedPhpDoc->acceptsNamedArguments();
 			$isReadOnly = $isReadOnly || $resolvedPhpDoc->isReadOnly();
 			$asserts = Assertions::createFromResolvedPhpDocBlock($resolvedPhpDoc);
+			$selfOutType = $resolvedPhpDoc->getSelfOutTag() !== null ? $resolvedPhpDoc->getSelfOutTag()->getType() : null;
 		}
 
-		return [$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, $isReadOnly, $docComment, $asserts];
+		return [$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, $isReadOnly, $docComment, $asserts, $selfOutType];
 	}
 
 	private function transformStaticType(ClassReflection $declaringClass, Type $type): Type

src/Node/InClassMethodNode.php

@@ -3,21 +3,21 @@
 namespace PHPStan\Node;
 
 use PhpParser\Node;
-use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\ExtendedMethodReflection;
 
 /** @api */
 class InClassMethodNode extends Node\Stmt implements VirtualNode
 {
 
 	public function __construct(
-		private MethodReflection $methodReflection,
+		private ExtendedMethodReflection $methodReflection,
 		private Node\Stmt\ClassMethod $originalNode,
 	)
 	{
 		parent::__construct($originalNode->getAttributes());
 	}
 
-	public function getMethodReflection(): MethodReflection
+	public function getMethodReflection(): ExtendedMethodReflection
 	{
 		return $this->methodReflection;
 	}

src/PhpDoc/PhpDocNodeResolver.php

@@ -14,6 +14,7 @@
 use PHPStan\PhpDoc\Tag\ParamTag;
 use PHPStan\PhpDoc\Tag\PropertyTag;
 use PHPStan\PhpDoc\Tag\ReturnTag;
+use PHPStan\PhpDoc\Tag\SelfOutTypeTag;
 use PHPStan\PhpDoc\Tag\TemplateTag;
 use PHPStan\PhpDoc\Tag\ThrowsTag;
 use PHPStan\PhpDoc\Tag\TypeAliasImportTag;
@@ -35,6 +36,7 @@
 use function array_reverse;
 use function count;
 use function in_array;
+use function method_exists;
 use function strpos;
 use function substr;
 
@@ -451,6 +453,22 @@ private function resolveAssertTagsFor(PhpDocNode $phpDocNode, NameScope $nameSco
 		return $resolved;
 	}
 
+	public function resolveSelfOutTypeTag(PhpDocNode $phpDocNode, NameScope $nameScope): ?SelfOutTypeTag
+	{
+		if (!method_exists($phpDocNode, 'getSelfOutTypeTagValues')) {
+			return null;
+		}
+
+		foreach (['@phpstan-this-out', '@phpstan-self-out', '@psalm-this-out', '@psalm-self-out'] as $tagName) {
+			foreach ($phpDocNode->getSelfOutTypeTagValues($tagName) as $selfOutTypeTagValue) {
+				$type = $this->typeNodeResolver->resolve($selfOutTypeTagValue->type, $nameScope);
+				return new SelfOutTypeTag($type);
+			}
+		}
+
+		return null;
+	}
+
 	public function resolveDeprecatedTag(PhpDocNode $phpDocNode, NameScope $nameScope): ?DeprecatedTag
 	{
 		foreach ($phpDocNode->getDeprecatedTagValues() as $deprecatedTagValue) {

src/PhpDoc/ResolvedPhpDocBlock.php

@@ -12,6 +12,7 @@
 use PHPStan\PhpDoc\Tag\ParamTag;
 use PHPStan\PhpDoc\Tag\PropertyTag;
 use PHPStan\PhpDoc\Tag\ReturnTag;
+use PHPStan\PhpDoc\Tag\SelfOutTypeTag;
 use PHPStan\PhpDoc\Tag\TemplateTag;
 use PHPStan\PhpDoc\Tag\ThrowsTag;
 use PHPStan\PhpDoc\Tag\TypeAliasImportTag;
@@ -90,6 +91,8 @@ class ResolvedPhpDocBlock
 	/** @var array<AssertTag>|false */
 	private array|false $assertTags = false;
 
+	private SelfOutTypeTag|false|null $selfOutTypeTag = false;
+
 	private DeprecatedTag|false|null $deprecatedTag = false;
 
 	private ?bool $isDeprecated = null;
@@ -164,6 +167,7 @@ public static function createEmpty(): self
 		$self->typeAliasTags = [];
 		$self->typeAliasImportTags = [];
 		$self->assertTags = [];
+		$self->selfOutTypeTag = null;
 		$self->deprecatedTag = null;
 		$self->isDeprecated = false;
 		$self->isInternal = false;
@@ -216,6 +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 = self::mergeSelfOutTypeTags($this->getSelfOutTag(), $parents);
 		$result->deprecatedTag = self::mergeDeprecatedTags($this->getDeprecatedTag(), $parents);
 		$result->isDeprecated = $result->deprecatedTag !== null;
 		$result->isInternal = $this->isInternal();
@@ -297,6 +302,7 @@ public function changeParameterNamesByMapping(array $parameterNameMapping): self
 		$self->typeAliasTags = $this->typeAliasTags;
 		$self->typeAliasImportTags = $this->typeAliasImportTags;
 		$self->assertTags = $assertTags;
+		$self->selfOutTypeTag = $this->selfOutTypeTag;
 		$self->deprecatedTag = $this->deprecatedTag;
 		$self->isDeprecated = $this->isDeprecated;
 		$self->isInternal = $this->isInternal;
@@ -522,6 +528,18 @@ public function getAssertTags(): array
 		return $this->assertTags;
 	}
 
+	public function getSelfOutTag(): ?SelfOutTypeTag
+	{
+		if ($this->selfOutTypeTag === false) {
+			$this->selfOutTypeTag = $this->phpDocNodeResolver->resolveSelfOutTypeTag(
+				$this->phpDocNode,
+				$this->getNameScope(),
+			);
+		}
+
+		return $this->selfOutTypeTag;
+	}
+
 	public function getDeprecatedTag(): ?DeprecatedTag
 	{
 		if (is_bool($this->deprecatedTag)) {
@@ -793,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/PhpDoc/Tag/SelfOutTypeTag.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\PhpDoc\Tag;
+
+use PHPStan\Type\Type;
+
+class SelfOutTypeTag implements TypedTag
+{
+
+	public function __construct(private Type $type)
+	{
+	}
+
+	public function getType(): Type
+	{
+		return $this->type;
+	}
+
+	/**
+	 * @return self
+	 */
+	public function withType(Type $type): TypedTag
+	{
+		return new self($type);
+	}
+
+}

src/Reflection/Annotations/AnnotationMethodReflection.php

@@ -121,4 +121,9 @@ public function getAsserts(): Assertions
 		return Assertions::createEmpty();
 	}
 
+	public function getSelfOutType(): ?Type
+	{
+		return null;
+	}
+
 }

src/Reflection/Dummy/ChangedTypeMethodReflection.php

@@ -95,4 +95,9 @@ public function getAsserts(): Assertions
 		return $this->reflection->getAsserts();
 	}
 
+	public function getSelfOutType(): ?Type
+	{
+		return $this->reflection->getSelfOutType();
+	}
+
 }

src/Reflection/Dummy/DummyMethodReflection.php

@@ -102,4 +102,9 @@ public function getAsserts(): Assertions
 		return Assertions::createEmpty();
 	}
 
+	public function getSelfOutType(): ?Type
+	{
+		return null;
+	}
+
 }

src/Reflection/ExtendedMethodReflection.php

@@ -2,6 +2,8 @@
 
 namespace PHPStan\Reflection;
 
+use PHPStan\Type\Type;
+
 /**
  * The purpose of this interface is to be able to
  * answer more questions about methods
@@ -18,4 +20,6 @@ interface ExtendedMethodReflection extends MethodReflection
 
 	public function getAsserts(): Assertions;
 
+	public function getSelfOutType(): ?Type;
+
 }

src/Reflection/Native/NativeMethodReflection.php

@@ -31,6 +31,7 @@ public function __construct(
 		private TrinaryLogic $hasSideEffects,
 		private ?Type $throwType,
 		private Assertions $assertions,
+		private ?Type $selfOutType,
 	)
 	{
 	}
@@ -160,4 +161,9 @@ public function getAsserts(): Assertions
 		return $this->assertions;
 	}
 
+	public function getSelfOutType(): ?Type
+	{
+		return $this->selfOutType;
+	}
+
 }

src/Reflection/Php/ClosureCallMethodReflection.php

@@ -124,4 +124,9 @@ public function getAsserts(): Assertions
 		return $this->nativeMethodReflection->getAsserts();
 	}
 
+	public function getSelfOutType(): ?Type
+	{
+		return $this->nativeMethodReflection->getSelfOutType();
+	}
+
 }

src/Reflection/Php/EnumCasesMethodReflection.php

@@ -111,4 +111,9 @@ public function getAsserts(): Assertions
 		return Assertions::createEmpty();
 	}
 
+	public function getSelfOutType(): ?Type
+	{
+		return null;
+	}
+
 }