Add @phpstan-self-out support

Author: rvanvelzen

composer.json

@@ -24,7 +24,7 @@
 		"ondram/ci-detector": "^3.4.0",
 		"ondrejmirtes/better-reflection": "6.1.0",
 		"phpstan/php-8-stubs": "0.3.38",
-		"phpstan/phpdoc-parser": "1.8.0",
+		"phpstan/phpdoc-parser": "dev-self-out",
 		"react/async": "^3",
 		"react/child-process": "^0.6.4",
 		"react/event-loop": "^1.2",
@@ -61,6 +61,12 @@
 		"rector/rector": "^0.14.3",
 		"vaimo/composer-patches": "^4.22"
 	},
+	"repositories": [
+		{
+			"type": "vcs",
+			"url": "https://github.com/rvanvelzen/phpdoc-parser"
+		}
+	],
 	"config": {
 		"platform": {
 			"php": "8.1.99"

composer.lock

@@ -166,6 +166,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

phpstan-baseline.neon

@@ -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/MutatingScope.php

@@ -468,7 +468,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 +491,7 @@ private function processStmtNode(
 				$isPure,
 				$acceptsNamedArguments,
 				$asserts,
+				$selfOutType,
 			);
 
 			if ($stmt->name->toLowerString() === '__construct') {
@@ -2057,6 +2058,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);
 			}
@@ -3968,7 +3976,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
 	{
@@ -3984,6 +3992,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;
@@ -4093,9 +4102,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->getThisOutTag() !== null ? $resolvedPhpDoc->getThisOutTag()->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/Analyser/NodeScopeResolver.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;
@@ -451,6 +452,18 @@ private function resolveAssertTagsFor(PhpDocNode $phpDocNode, NameScope $nameSco
 		return $resolved;
 	}
 
+	public function resolveSelfOutTypeTag(PhpDocNode $phpDocNode, NameScope $nameScope): ?SelfOutTypeTag
+	{
+		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/PhpDocNodeResolver.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 = $this->getThisOutTag();
 		$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->getThisOutTag();
 		$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 getThisOutTag(): ?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)) {

src/PhpDoc/ResolvedPhpDocBlock.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/PhpDoc/Tag/SelfOutTypeTag.php

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

src/Reflection/Annotations/AnnotationMethodReflection.php

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