Add @param-out support

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 'getParamOutTypeTagV…' will always evaluate to true\\.$#"
+			count: 1
+			path: src/PhpDoc/PhpDocNodeResolver.php
+
 		-
 			message: "#^Call to function method_exists\\(\\) with PHPStan\\\\PhpDocParser\\\\Ast\\\\PhpDoc\\\\PhpDocNode and 'getSelfOutTypeTagVa…' will always evaluate to true\\.$#"
 			count: 1
@@ -161,6 +166,11 @@ parameters:
 			count: 1
 			path: src/PhpDoc/StubValidator.php
 
+		-
+			message: "#^Return type \\(PHPStan\\\\PhpDoc\\\\Tag\\\\ParamOutTag\\) of method PHPStan\\\\PhpDoc\\\\Tag\\\\ParamOutTag\\:\\: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/ParamOutTag.php
+
 		-
 			message: "#^Return type \\(PHPStan\\\\PhpDoc\\\\Tag\\\\ParamTag\\) of method PHPStan\\\\PhpDoc\\\\Tag\\\\ParamTag\\:\\: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

@@ -2517,6 +2517,7 @@ public function enterTrait(ClassReflection $traitReflection): self
 	/**
 	 * @api
 	 * @param Type[] $phpDocParameterTypes
+	 * @param Type[] $parameterOutTypes
 	 */
 	public function enterClassMethod(
 		Node\Stmt\ClassMethod $classMethod,
@@ -2533,6 +2534,7 @@ public function enterClassMethod(
 		?Assertions $asserts = null,
 		?Type $selfOutType = null,
 		?string $phpDocComment = null,
+		array $parameterOutTypes = [],
 	): self
 	{
 		if (!$this->isInClass()) {
@@ -2560,6 +2562,7 @@ public function enterClassMethod(
 				$asserts ?? Assertions::createEmpty(),
 				$selfOutType,
 				$phpDocComment,
+				array_map(static fn (Type $type): Type => TemplateTypeHelper::toArgument($type), $parameterOutTypes),
 			),
 			!$classMethod->isStatic(),
 		);
@@ -2626,6 +2629,7 @@ private function getRealParameterDefaultValues(Node\FunctionLike $functionLike):
 	/**
 	 * @api
 	 * @param Type[] $phpDocParameterTypes
+	 * @param Type[] $parameterOutTypes
 	 */
 	public function enterFunction(
 		Node\Stmt\Function_ $function,
@@ -2641,6 +2645,7 @@ public function enterFunction(
 		bool $acceptsNamedArguments = true,
 		?Assertions $asserts = null,
 		?string $phpDocComment = null,
+		array $parameterOutTypes = [],
 	): self
 	{
 		return $this->enterFunctionLike(
@@ -2662,6 +2667,7 @@ public function enterFunction(
 				$acceptsNamedArguments,
 				$asserts ?? Assertions::createEmpty(),
 				$phpDocComment,
+				array_map(static fn (Type $type): Type => TemplateTypeHelper::toArgument($type), $parameterOutTypes),
 			),
 			false,
 		);

src/Analyser/NodeScopeResolver.php

@@ -114,6 +114,7 @@
 use PHPStan\Reflection\MethodReflection;
 use PHPStan\Reflection\Native\NativeMethodReflection;
 use PHPStan\Reflection\Native\NativeParameterReflection;
+use PHPStan\Reflection\ParameterReflectionWithPhpDocs;
 use PHPStan\Reflection\ParametersAcceptor;
 use PHPStan\Reflection\ParametersAcceptorSelector;
 use PHPStan\Reflection\Php\PhpMethodReflection;
@@ -407,7 +408,7 @@ private function processStmtNode(
 			$hasYield = false;
 			$throwPoints = [];
 			$this->processAttributeGroups($stmt->attrGroups, $scope, $nodeCallback);
-			[$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, , $phpDocComment, $asserts] = $this->getPhpDocs($scope, $stmt);
+			[$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, , $phpDocComment, $asserts,, $phpDocParameterOutTypes] = $this->getPhpDocs($scope, $stmt);
 
 			foreach ($stmt->params as $param) {
 				$this->processParamNode($param, $scope, $nodeCallback);
@@ -431,6 +432,7 @@ private function processStmtNode(
 				$acceptsNamedArguments,
 				$asserts,
 				$phpDocComment,
+				$phpDocParameterOutTypes,
 			);
 			$functionReflection = $functionScope->getFunction();
 			if (!$functionReflection instanceof FunctionReflection) {
@@ -470,7 +472,7 @@ private function processStmtNode(
 			$hasYield = false;
 			$throwPoints = [];
 			$this->processAttributeGroups($stmt->attrGroups, $scope, $nodeCallback);
-			[$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, , $phpDocComment, $asserts, $selfOutType] = $this->getPhpDocs($scope, $stmt);
+			[$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, , $phpDocComment, $asserts, $selfOutType, $phpDocParameterOutTypes] = $this->getPhpDocs($scope, $stmt);
 
 			foreach ($stmt->params as $param) {
 				$this->processParamNode($param, $scope, $nodeCallback);
@@ -495,6 +497,7 @@ private function processStmtNode(
 				$asserts,
 				$selfOutType,
 				$phpDocComment,
+				$phpDocParameterOutTypes,
 			);
 
 			if ($stmt->name->toLowerString() === '__construct') {
@@ -1806,6 +1809,7 @@ function (MutatingScope $scope) use ($expr, $nodeCallback, $context): Expression
 					$functionReflection->getVariants(),
 				);
 			}
+
 			if ($parametersAcceptor !== null) {
 				$expr = ArgumentsNormalizer::reorderFuncArguments($parametersAcceptor, $expr) ?? $expr;
 			}
@@ -2043,11 +2047,13 @@ static function (?Type $offsetType, Type $valueType, bool $optional) use (&$arra
 					}
 				}
 			}
+
 			if ($parametersAcceptor !== null) {
 				$expr = ArgumentsNormalizer::reorderMethodArguments($parametersAcceptor, $expr) ?? $expr;
 			}
 			$result = $this->processArgs($methodReflection, $parametersAcceptor, $expr->getArgs(), $scope, $nodeCallback, $context);
 			$scope = $result->getScope();
+
 			if ($methodReflection !== null) {
 				$hasSideEffects = $methodReflection->hasSideEffects();
 				if ($hasSideEffects->yes() || $methodReflection->getName() === '__construct') {
@@ -2174,12 +2180,14 @@ static function (?Type $offsetType, Type $valueType, bool $optional) use (&$arra
 					$throwPoints[] = ThrowPoint::createImplicit($scope, $expr);
 				}
 			}
+
 			if ($parametersAcceptor !== null) {
 				$expr = ArgumentsNormalizer::reorderStaticCallArguments($parametersAcceptor, $expr) ?? $expr;
 			}
 			$result = $this->processArgs($methodReflection, $parametersAcceptor, $expr->getArgs(), $scope, $nodeCallback, $context, $closureBindScope ?? null);
 			$scope = $result->getScope();
 			$scopeFunction = $scope->getFunction();
+
 			if (
 				$methodReflection !== null
 				&& !$methodReflection->isStatic()
@@ -2529,6 +2537,7 @@ static function (?Type $offsetType, Type $valueType, bool $optional) use (&$arra
 					$throwPoints[] = ThrowPoint::createImplicit($scope, $expr);
 				}
 			}
+
 			if ($parametersAcceptor !== null) {
 				$expr = ArgumentsNormalizer::reorderNewArguments($parametersAcceptor, $expr) ?? $expr;
 			}
@@ -3272,8 +3281,21 @@ private function processArgs(
 		?MutatingScope $closureBindScope = null,
 	): ExpressionResult
 	{
+		$paramOutTypes = [];
 		if ($parametersAcceptor !== null) {
 			$parameters = $parametersAcceptor->getParameters();
+
+			foreach ($parameters as $parameter) {
+				if (!$parameter instanceof ParameterReflectionWithPhpDocs) {
+					continue;
+				}
+
+				if ($parameter->getOutType() === null) {
+					continue;
+				}
+
+				$paramOutTypes[$parameter->getName()] = TemplateTypeHelper::resolveTemplateTypes($parameter->getOutType(), $parametersAcceptor->getResolvedTemplateTypeMap());
+			}
 		}
 
 		if ($calleeReflection !== null) {
@@ -3286,20 +3308,29 @@ private function processArgs(
 			$originalArg = $arg->getAttribute(ArgumentsNormalizer::ORIGINAL_ARG_ATTRIBUTE) ?? $arg;
 			$nodeCallback($originalArg, $scope);
 			if (isset($parameters) && $parametersAcceptor !== null) {
+				$byRefType = new MixedType();
 				$assignByReference = false;
 				if (isset($parameters[$i])) {
 					$assignByReference = $parameters[$i]->passedByReference()->createsNewVariable();
 					$parameterType = $parameters[$i]->getType();
+
+					if (isset($paramOutTypes[$parameters[$i]->getName()])) {
+						$byRefType = $paramOutTypes[$parameters[$i]->getName()];
+					}
 				} elseif (count($parameters) > 0 && $parametersAcceptor->isVariadic()) {
 					$lastParameter = $parameters[count($parameters) - 1];
 					$assignByReference = $lastParameter->passedByReference()->createsNewVariable();
 					$parameterType = $lastParameter->getType();
+
+					if (isset($paramOutTypes[$lastParameter->getName()])) {
+						$byRefType = $paramOutTypes[$lastParameter->getName()];
+					}
 				}
 
 				if ($assignByReference) {
 					$argValue = $arg->value;
 					if ($argValue instanceof Variable && is_string($argValue->name)) {
-						$scope = $scope->assignVariable($argValue->name, new MixedType(), new MixedType());
+						$scope = $scope->assignVariable($argValue->name, $byRefType, new MixedType());
 					}
 				}
 			}
@@ -4039,7 +4070,7 @@ private function processNodesForTraitUse($node, ClassReflection $traitReflection
 	}
 
 	/**
-	 * @return array{TemplateTypeMap, Type[], ?Type, ?Type, ?string, bool, bool, bool, bool|null, bool, bool, string|null, Assertions, ?Type}
+	 * @return array{TemplateTypeMap, array<string, Type>, ?Type, ?Type, ?string, bool, bool, bool, bool|null, bool, bool, string|null, Assertions, ?Type, array<string, Type>}
 	 */
 	public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $node): array
 	{
@@ -4065,6 +4096,7 @@ public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $n
 		$trait = $scope->isInTrait() ? $scope->getTraitReflection()->getName() : null;
 		$resolvedPhpDoc = null;
 		$functionName = null;
+		$phpDocParameterOutTypes = [];
 
 		if ($node instanceof Node\Stmt\ClassMethod) {
 			if (!$scope->isInClass()) {
@@ -4149,6 +4181,9 @@ public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $n
 				}
 				$phpDocParameterTypes[$paramName] = $paramType;
 			}
+			foreach ($resolvedPhpDoc->getParamOutTags() as $paramName => $paramOutTag) {
+				$phpDocParameterOutTypes[$paramName] = $paramOutTag->getType();
+			}
 			if ($node instanceof Node\FunctionLike) {
 				$nativeReturnType = $scope->getFunctionType($node->getReturnType(), false, false);
 				$phpDocReturnType = $this->getPhpDocReturnType($resolvedPhpDoc, $nativeReturnType);
@@ -4168,7 +4203,7 @@ public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $n
 			$selfOutType = $resolvedPhpDoc->getSelfOutTag() !== null ? $resolvedPhpDoc->getSelfOutTag()->getType() : null;
 		}
 
-		return [$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, $isReadOnly, $docComment, $asserts, $selfOutType];
+		return [$templateTypeMap, $phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, $isReadOnly, $docComment, $asserts, $selfOutType, $phpDocParameterOutTypes];
 	}
 
 	private function transformStaticType(ClassReflection $declaringClass, Type $type): Type

src/PhpDoc/PhpDocNodeResolver.php

@@ -11,6 +11,7 @@
 use PHPStan\PhpDoc\Tag\MethodTag;
 use PHPStan\PhpDoc\Tag\MethodTagParameter;
 use PHPStan\PhpDoc\Tag\MixinTag;
+use PHPStan\PhpDoc\Tag\ParamOutTag;
 use PHPStan\PhpDoc\Tag\ParamTag;
 use PHPStan\PhpDoc\Tag\PropertyTag;
 use PHPStan\PhpDoc\Tag\ReturnTag;
@@ -318,6 +319,34 @@ public function resolveParamTags(PhpDocNode $phpDocNode, NameScope $nameScope):
 		return $resolved;
 	}
 
+	/**
+	 * @return array<string, ParamOutTag>
+	 */
+	public function resolveParamOutTags(PhpDocNode $phpDocNode, NameScope $nameScope): array
+	{
+		if (!method_exists($phpDocNode, 'getParamOutTypeTagValues')) {
+			return [];
+		}
+
+		$resolved = [];
+
+		foreach (['@param-out', '@psalm-param-out', '@phpstan-param-out'] as $tagName) {
+			foreach ($phpDocNode->getParamOutTypeTagValues($tagName) as $tagValue) {
+				$parameterName = substr($tagValue->parameterName, 1);
+				$parameterType = $this->typeNodeResolver->resolve($tagValue->type, $nameScope);
+				if ($this->shouldSkipType($tagName, $parameterType)) {
+					continue;
+				}
+
+				$resolved[$parameterName] = new ParamOutTag(
+					$parameterType,
+				);
+			}
+		}
+
+		return $resolved;
+	}
+
 	public function resolveReturnTag(PhpDocNode $phpDocNode, NameScope $nameScope): ?ReturnTag
 	{
 		$resolved = null;