Check the body of @pure-unless-callable-is-impure functions for purity

A function/method declared @pure-unless-callable-is-impure $f is pure except for the flagged callable, so its body is now checked by FunctionPurityCheck: impure statements outside the callable (e.g. echo) are reported, while the flagged callable's own invocation is exempt. Thread the parameter flags through enterFunction() so the check sees them on plain functions too.
ondrejmirtes · Jul 7, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
commit 33926fe470fafb6e0bf91d5cd32526139a291745
diff --git a/src/Analyser/NodeScopeResolver.php b/src/Analyser/NodeScopeResolver.php
@@ -779,7 +779,7 @@ public function processStmtNode(
 			$throwPoints = [];
 			$impurePoints = [];
 			$this->processAttributeGroups($stmt, $stmt->attrGroups, $scope, $storage, $nodeCallback);
-			[$templateTypeMap, $phpDocParameterTypes, $phpDocImmediatelyInvokedCallableParameters, $phpDocClosureThisTypeParameters, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, , $isPure, $acceptsNamedArguments, , $phpDocComment, $asserts,, $phpDocParameterOutTypes] = $this->getPhpDocs($scope, $stmt);
+			[$templateTypeMap, $phpDocParameterTypes, $phpDocImmediatelyInvokedCallableParameters, $phpDocClosureThisTypeParameters, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, , $isPure, $acceptsNamedArguments, , $phpDocComment, $asserts,, $phpDocParameterOutTypes, , , , $pureUnlessCallableIsImpureParameters] = $this->getPhpDocs($scope, $stmt);
 
 			foreach ($stmt->params as $param) {
 				$this->processParamNode($stmt, $param, $scope, $storage, $nodeCallback);
@@ -809,6 +809,7 @@ public function processStmtNode(
 				$phpDocParameterOutTypes,
 				$phpDocImmediatelyInvokedCallableParameters,
 				$phpDocClosureThisTypeParameters,
+				$pureUnlessCallableIsImpureParameters,
 			);
 			$functionReflection = $functionScope->getFunction();
 			if (!$functionReflection instanceof PhpFunctionFromParserNodeReflection) {

diff --git a/src/Rules/Pure/FunctionPurityCheck.php b/src/Rules/Pure/FunctionPurityCheck.php
@@ -3,6 +3,7 @@
 namespace PHPStan\Rules\Pure;
 
 use PhpParser\Node\Expr\FuncCall;
+use PhpParser\Node\Expr\Variable;
 use PhpParser\Node\Name;
 use PhpParser\Node\Stmt;
 use PHPStan\Analyser\ImpurePoint;
@@ -16,8 +17,11 @@
 use PHPStan\Rules\RuleErrorBuilder;
 use PHPStan\Type\Type;
 use function array_filter;
+use function array_key_exists;
+use function array_merge;
 use function count;
 use function in_array;
+use function is_string;
 use function lcfirst;
 use function sprintf;
 
@@ -48,6 +52,15 @@ public function check(
 		$errors = [];
 		$isPure = $functionReflection->isPure();
 
+		$pureUnlessCallableParamNames = [];
+		foreach ($parameters as $parameter) {
+			if (!$parameter->isPureUnlessCallableIsImpureParameter()->yes()) {
+				continue;
+			}
+
+			$pureUnlessCallableParamNames[$parameter->getName()] = true;
+		}
+
 		if ($isPure->yes()) {
 			foreach ($parameters as $parameter) {
 				if (!$parameter->passedByReference()->createsNewVariable()) {
@@ -74,21 +87,12 @@ public function check(
 				))->identifier(sprintf('pure%s.void', $identifier))->build();
 			}
 
-			foreach ($impurePoints as $impurePoint) {
-				$errors[] = RuleErrorBuilder::message(sprintf(
-					'%s %s in pure %s.',
-					$impurePoint->isCertain() ? 'Impure' : 'Possibly impure',
-					$impurePoint->getDescription(),
-					lcfirst($functionDescription),
-				))
-					->line($impurePoint->getNode()->getStartLine())
-					->identifier(sprintf(
-						'%s.%s',
-						$impurePoint->isCertain() ? 'impure' : 'possiblyImpure',
-						$impurePoint->getIdentifier(),
-					))
-					->build();
-			}
+			$errors = array_merge($errors, $this->reportImpurePoints($impurePoints, $pureUnlessCallableParamNames, $functionDescription));
+		} elseif ($pureUnlessCallableParamNames !== []) {
+			// A function declared @pure-unless-callable-is-impure is pure except
+			// for the flagged callables, so its body is checked for purity while
+			// the flagged callables' own invocations are exempt.
+			$errors = array_merge($errors, $this->reportImpurePoints($impurePoints, $pureUnlessCallableParamNames, $functionDescription));
 		} elseif ($isPure->no()) {
 			if (
 				count($throwPoints) === 0
@@ -153,4 +157,58 @@ public function check(
 		return $errors;
 	}
 
+	/**
+	 * @param ImpurePoint[] $impurePoints
+	 * @param array<string, true> $pureUnlessCallableParamNames
+	 * @return list<IdentifierRuleError>
+	 */
+	private function reportImpurePoints(array $impurePoints, array $pureUnlessCallableParamNames, string $functionDescription): array
+	{
+		$errors = [];
+		foreach ($impurePoints as $impurePoint) {
+			if ($this->isPureUnlessCallableInvocation($impurePoint, $pureUnlessCallableParamNames)) {
+				continue;
+			}
+
+			$errors[] = RuleErrorBuilder::message(sprintf(
+				'%s %s in pure %s.',
+				$impurePoint->isCertain() ? 'Impure' : 'Possibly impure',
+				$impurePoint->getDescription(),
+				lcfirst($functionDescription),
+			))
+				->line($impurePoint->getNode()->getStartLine())
+				->identifier(sprintf(
+					'%s.%s',
+					$impurePoint->isCertain() ? 'impure' : 'possiblyImpure',
+					$impurePoint->getIdentifier(),
+				))
+				->build();
+		}
+
+		return $errors;
+	}
+
+	/**
+	 * @param array<string, true> $pureUnlessCallableParamNames
+	 */
+	private function isPureUnlessCallableInvocation(ImpurePoint $impurePoint, array $pureUnlessCallableParamNames): bool
+	{
+		if ($pureUnlessCallableParamNames === []) {
+			return false;
+		}
+
+		$node = $impurePoint->getNode();
+		if (!$node instanceof FuncCall) {
+			return false;
+		}
+		if (!$node->name instanceof Variable) {
+			return false;
+		}
+		if (!is_string($node->name->name)) {
+			return false;
+		}
+
+		return array_key_exists($node->name->name, $pureUnlessCallableParamNames);
+	}
+
 }
diff --git a/tests/PHPStan/Rules/Pure/PureFunctionRuleTest.php b/tests/PHPStan/Rules/Pure/PureFunctionRuleTest.php
@@ -277,6 +277,10 @@ public function testPureUnlessCallableIsImpure(): void
 				'Possibly impure instantiation of class PureUnlessCallableIsImpureFunction\Baz in pure function PureUnlessCallableIsImpureFunction\pureInstantiatingWithUnionCallback().',
 				238,
 			],
+			[
+				'Impure echo in pure function PureUnlessCallableIsImpureFunction\pureUnlessCallableWithImpureStatementOutsideCallback().',
+				253,
+			],
 		]);
 	}
 

diff --git a/tests/PHPStan/Rules/Pure/data/pure-unless-callable-is-impure.php b/tests/PHPStan/Rules/Pure/data/pure-unless-callable-is-impure.php
@@ -239,3 +239,22 @@ function pureInstantiatingWithUnionCallback(callable $pureCb, callable $cb, bool
 
 	return 1;
 }
+
+/**
+ * @param callable(int): int $f
+ * @param array<int> $arr
+ * @return array<int>
+ * @pure-unless-callable-is-impure $f
+ */
+function pureUnlessCallableWithImpureStatementOutsideCallback(callable $f, array $arr): array
+{
+	// The function is pure except for $f, so a side effect outside $f is reported,
+	// while the $f() invocation itself is exempt.
+	echo 'side effect';
+	$result = [];
+	foreach ($arr as $i => $v) {
+		$result[$i] = $f($v);
+	}
+
+	return $result;
+}
-Original file line number
+Diff line change
@@ Expand Up / @@ -277,6 +277,10 @@ public function testPureUnlessCallableIsImpure(): void @@
     				'Possibly impure instantiation of class PureUnlessCallableIsImpureFunction\Baz in pure function PureUnlessCallableIsImpureFunction\pureInstantiatingWithUnionCallback().',
 ,
     			],
+    			[
+    				'Impure echo in pure function PureUnlessCallableIsImpureFunction\pureUnlessCallableWithImpureStatementOutsideCallback().',
+,
+    			],
     		]);
     	}
@@ Expand Down @@