Support for @pure-unless-parameter-passed

Author: staabm

src/Ast/PhpDoc/PhpDocNode.php

@@ -126,6 +126,17 @@ public function getPureUnlessCallableIsImpureTagValues(string $tagName = '@pure-
 		);
 	}
 
+	/**
+	 * @return PureUnlessParameterIsPassedTagValueNode[]
+	 */
+	public function getPureUnlessParameterIsPassedTagValues(string $tagName = '@pure-unless-parameter-passed'): array
+	{
+		return array_filter(
+			array_column($this->getTagsByName($tagName), 'value'),
+			static fn (PhpDocTagValueNode $value): bool => $value instanceof PureUnlessParameterIsPassedTagValueNode,
+		);
+	}
+
 	/**
 	 * @return TemplateTagValueNode[]
 	 */

src/Ast/PhpDoc/PureUnlessParameterIsPassedTagValueNode.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\PhpDocParser\Ast\PhpDoc;
+
+use PHPStan\PhpDocParser\Ast\NodeAttributes;
+use function trim;
+
+class PureUnlessParameterIsPassedTagValueNode implements PhpDocTagValueNode
+{
+
+	use NodeAttributes;
+
+	public string $parameterName;
+
+	/** @var string (may be empty) */
+	public string $description;
+
+	public function __construct(string $parameterName, string $description)
+	{
+		$this->parameterName = $parameterName;
+		$this->description = $description;
+	}
+
+	public function __toString(): string
+	{
+		return trim("{$this->parameterName} {$this->description}");
+	}
+
+}

src/Parser/PhpDocParser.php

@@ -358,6 +358,11 @@ public function parseTagValue(TokenIterator $tokens, string $tag): Ast\PhpDoc\Ph
 					$tagValue = $this->parsePureUnlessCallableIsImpureTagValue($tokens);
 					break;
 
+				case '@pure-unless-parameter-passed':
+				case '@phpstan-pure-unless-parameter-passed':
+					$tagValue = $this->parsePureUnlessParameterIsPassed($tokens);
+					break;
+
 				case '@var':
 				case '@phpstan-var':
 				case '@psalm-var':
@@ -878,6 +883,14 @@ private function parsePureUnlessCallableIsImpureTagValue(TokenIterator $tokens):
 		return new Ast\PhpDoc\PureUnlessCallableIsImpureTagValueNode($parameterName, $description);
 	}
 
+	private function parsePureUnlessParameterIsPassed(TokenIterator $tokens): Ast\PhpDoc\PureUnlessParameterIsPassedTagValueNode
+	{
+		$parameterName = $this->parseRequiredVariableName($tokens);
+		$description = $this->parseOptionalDescription($tokens, false);
+
+		return new Ast\PhpDoc\PureUnlessParameterIsPassedTagValueNode($parameterName, $description);
+	}
+
 	private function parseVarTagValue(TokenIterator $tokens): Ast\PhpDoc\VarTagValueNode
 	{
 		$type = $this->typeParser->parse($tokens);

src/Printer/Printer.php

@@ -32,6 +32,7 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTextNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PropertyTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PureUnlessCallableIsImpureTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PureUnlessParameterIsPassedTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\RequireExtendsTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\RequireImplementsTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
@@ -346,6 +347,9 @@ private function printTagValue(PhpDocTagValueNode $node): string
 		if ($node instanceof PureUnlessCallableIsImpureTagValueNode) {
 			return trim("{$node->parameterName} {$node->description}");
 		}
+		if ($node instanceof PureUnlessParameterIsPassedTagValueNode) {
+			return trim("{$node->parameterName} {$node->description}");
+		}
 		if ($node instanceof PropertyTagValueNode) {
 			$type = $this->printType($node->type);
 			return trim("{$type} {$node->propertyName} {$node->description}");

tests/PHPStan/Parser/PhpDocParserTest.php

@@ -39,6 +39,7 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTextNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PropertyTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PureUnlessCallableIsImpureTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PureUnlessParameterIsPassedTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\RequireExtendsTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\RequireImplementsTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
@@ -753,6 +754,37 @@ public function providePureUnlessCallableIsImpureTagsData(): Iterator
 		];
 	}
 
+	public function providePureUnlessParameterIsPassedTagsData(): Iterator
+	{
+		yield [
+			'OK',
+			'/** @pure-unless-parameter-passed $foo */',
+			new PhpDocNode([
+				new PhpDocTagNode(
+					'@pure-unless-parameter-passed',
+					new PureUnlessParameterIsPassedTagValueNode(
+						'$foo',
+						'',
+					),
+				),
+			]),
+		];
+
+		yield [
+			'OK with description',
+			'/** @pure-unless-parameter-passed $foo test two three */',
+			new PhpDocNode([
+				new PhpDocTagNode(
+					'@pure-unless-parameter-passed',
+					new PureUnlessParameterIsPassedTagValueNode(
+						'$foo',
+						'test two three',
+					),
+				),
+			]),
+		];
+	}
+
 	public function provideVarTagsData(): Iterator
 	{
 		yield [

tests/PHPStan/Printer/PrinterTest.php

@@ -24,6 +24,7 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PureUnlessCallableIsImpureTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PureUnlessParameterIsPassedTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\TemplateTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\TypeAliasImportTagValueNode;
@@ -1788,6 +1789,24 @@ public function enterNode(Node $node)
 			},
 		];
 
+		yield [
+			'/** @pure-unless-parameter-passed $foo test */',
+			'/** @pure-unless-parameter-passed $bar foo */',
+			new class extends AbstractNodeVisitor {
+
+				public function enterNode(Node $node)
+				{
+					if ($node instanceof PureUnlessParameterIsPassedTagValueNode) {
+						$node->parameterName = '$bar';
+						$node->description = 'foo';
+					}
+
+					return $node;
+				}
+
+			},
+		];
+
 		yield [
 			'/** @return Foo[abc] */',
 			'/** @return self::FOO[abc] */',