Parse @pure-unless-parameter-passed PHPDoc tag

Resolve the tag into per-parameter flags and merge them across parent
PHPDocs. Until phpstan/phpdoc-parser#259 is merged the parser does not
understand the tag natively, so parse it from the generic tag value and
whitelist the @phpstan- alias in InvalidPHPStanDocTagRule.

Author: zonuexe

src/PhpDoc/PhpDocNodeResolver.php

@@ -28,6 +28,7 @@
 use PHPStan\PhpDoc\Tag\UsesTag;
 use PHPStan\PhpDoc\Tag\VarTag;
 use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprNullNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\GenericTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\MixinTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\TemplateTagValueNode;
@@ -47,8 +48,10 @@
 use function array_reverse;
 use function count;
 use function in_array;
+use function ltrim;
 use function method_exists;
 use function str_starts_with;
+use function strpos;
 use function substr;
 
 #[AutowiredService]
@@ -403,6 +406,46 @@ public function resolveParamPureUnlessCallableIsImpure(PhpDocNode $phpDocNode):
 		return $parameters;
 	}
 
+	/**
+	 * @return array<string, bool>
+	 */
+	public function resolveParamPureUnlessParameterPassed(PhpDocNode $phpDocNode): array
+	{
+		$parameters = [];
+		// TODO: replace this generic-tag parsing with
+		// $phpDocNode->getPureUnlessParameterIsPassedTagValues() once
+		// phpstan/phpdoc-parser#259 is merged and the parser understands the tag.
+		foreach (['@pure-unless-parameter-passed', '@phpstan-pure-unless-parameter-passed'] as $tagName) {
+			foreach ($phpDocNode->getTags() as $tag) {
+				if ($tag->name !== $tagName) {
+					continue;
+				}
+				if (!$tag->value instanceof GenericTagValueNode) {
+					continue;
+				}
+
+				$value = ltrim($tag->value->value);
+				if ($value === '' || $value[0] !== '$') {
+					continue;
+				}
+
+				$parameterName = substr($value, 1);
+				$spacePosition = strpos($parameterName, ' ');
+				if ($spacePosition !== false) {
+					$parameterName = substr($parameterName, 0, $spacePosition);
+				}
+
+				if ($parameterName === '') {
+					continue;
+				}
+
+				$parameters[$parameterName] = true;
+			}
+		}
+
+		return $parameters;
+	}
+
 	/**
 	 * @return array<string, ParamClosureThisTag>
 	 */

src/PhpDoc/ResolvedPhpDocBlock.php

@@ -99,6 +99,9 @@ final class ResolvedPhpDocBlock
 	/** @var array<string, bool>|false */
 	private array|false $paramsPureUnlessCallableIsImpure = false;
 
+	/** @var array<string, bool>|false */
+	private array|false $paramsPureUnlessParameterPassed = false;
+
 	/** @var array<string, ParamClosureThisTag>|false */
 	private array|false $paramClosureThisTags = false;
 
@@ -224,6 +227,7 @@ public static function createEmpty(): self
 		$self->paramOutTags = [];
 		$self->paramsImmediatelyInvokedCallable = [];
 		$self->paramsPureUnlessCallableIsImpure = [];
+		$self->paramsPureUnlessParameterPassed = [];
 		$self->paramClosureThisTags = [];
 		$self->returnTag = null;
 		$self->throwsTag = null;
@@ -281,6 +285,7 @@ public function merge(ResolvedPhpDocBlock $parent, InheritedPhpDocParameterMappi
 		$result->paramOutTags = self::mergeParamOutTags($this->getParamOutTags(), $parent, $parameterMapping, $parentClass);
 		$result->paramsImmediatelyInvokedCallable = self::mergeParamsImmediatelyInvokedCallable($this->getParamsImmediatelyInvokedCallable(), $parent, $parameterMapping);
 		$result->paramsPureUnlessCallableIsImpure = self::mergeParamsPureUnlessCallableIsImpure($this->getParamsPureUnlessCallableIsImpure(), $parent, $parameterMapping);
+		$result->paramsPureUnlessParameterPassed = self::mergeParamsPureUnlessParameterPassed($this->getParamsPureUnlessParameterPassed(), $parent, $parameterMapping);
 		$result->paramClosureThisTags = self::mergeParamClosureThisTags($this->getParamClosureThisTags(), $parent, $parameterMapping, $parentClass);
 		$result->returnTag = self::mergeReturnTags($this->getReturnTag(), $declaringClass, $parent, $parameterMapping, $parentClass);
 		$result->throwsTag = self::mergeThrowsTags($this->getThrowsTag(), $parent);
@@ -601,6 +606,18 @@ public function getParamsPureUnlessCallableIsImpure(): array
 		return $this->paramsPureUnlessCallableIsImpure;
 	}
 
+	/**
+	 * @return array<string, bool>
+	 */
+	public function getParamsPureUnlessParameterPassed(): array
+	{
+		if ($this->paramsPureUnlessParameterPassed === false) {
+			$this->paramsPureUnlessParameterPassed = $this->phpDocNodeResolver->resolveParamPureUnlessParameterPassed($this->phpDocNode);
+		}
+
+		return $this->paramsPureUnlessParameterPassed;
+	}
+
 	/**
 	 * @return array<string, ParamClosureThisTag>
 	 */
@@ -1130,6 +1147,34 @@ private static function mergeOneParentParamPureUnlessCallableIsImpure(array $par
 		return $paramsPureUnlessCallableIsImpure;
 	}
 
+	/**
+	 * @param array<string, bool> $paramsPureUnlessParameterPassed
+	 * @return array<string, bool>
+	 */
+	private static function mergeParamsPureUnlessParameterPassed(array $paramsPureUnlessParameterPassed, self $parent, InheritedPhpDocParameterMapping $parameterMapping): array
+	{
+		return self::mergeOneParentParamPureUnlessParameterPassed($paramsPureUnlessParameterPassed, $parent, $parameterMapping);
+	}
+
+	/**
+	 * @param array<string, bool> $paramsPureUnlessParameterPassed
+	 * @return array<string, bool>
+	 */
+	private static function mergeOneParentParamPureUnlessParameterPassed(array $paramsPureUnlessParameterPassed, self $parent, InheritedPhpDocParameterMapping $parameterMapping): array
+	{
+		$parentPureUnlessParameterPassed = $parameterMapping->transformArrayKeysWithParameterNameMapping($parent->getParamsPureUnlessParameterPassed());
+
+		foreach ($parentPureUnlessParameterPassed as $name => $parentIsPureUnlessParameterPassed) {
+			if (array_key_exists($name, $paramsPureUnlessParameterPassed)) {
+				continue;
+			}
+
+			$paramsPureUnlessParameterPassed[$name] = $parentIsPureUnlessParameterPassed;
+		}
+
+		return $paramsPureUnlessParameterPassed;
+	}
+
 	/**
 	 * @param array<string, ParamClosureThisTag> $paramsClosureThisTags
 	 * @return array<string, ParamClosureThisTag>

src/Rules/PhpDoc/InvalidPHPStanDocTagRule.php

@@ -64,6 +64,9 @@ final class InvalidPHPStanDocTagRule implements Rule
 		'@phpstan-param-immediately-invoked-callable',
 		'@phpstan-param-later-invoked-callable',
 		'@phpstan-param-closure-this',
+		// TODO: drop this once phpstan/phpdoc-parser#259 is merged and the parser
+		// recognizes the tag natively (like @phpstan-pure-unless-callable-is-impure).
+		'@phpstan-pure-unless-parameter-passed',
 		'@phpstan-all-methods-pure',
 		'@phpstan-all-methods-impure',
 	];