Report certain impurity when a @pure-unless-parameter-passed argument is passed

createFromVariant suppressed the impure point when the flagged parameter
was omitted, but never promoted the verdict to certain when it was
passed, unlike its @pure-unless-callable-is-impure sibling right above
it and unlike NewHandler's own constructor handling. Passing the
by-ref out-parameter is a definite side effect, not a possible one.

Also covers intersection types, method inheritance (incl. a renamed
parameter), and first-class callables.

Author: zonuexe

src/Reflection/Callables/SimpleImpurePoint.php

@@ -76,10 +76,15 @@ public static function createFromVariant(FunctionReflection|ExtendedMethodReflec
 
 			if (!$certain && $scope !== null && $variant !== null) {
 				$passedVerdict = self::resolvePureUnlessParameterPassedVerdict($variant, $args);
-				if ($passedVerdict !== null && $passedVerdict->yes()) {
-					// None of the @pure-unless-parameter-passed by-ref parameters
-					// received an argument, so the call is pure.
-					return null;
+				if ($passedVerdict !== null) {
+					if ($passedVerdict->yes()) {
+						// None of the @pure-unless-parameter-passed by-ref parameters
+						// received an argument, so the call is pure.
+						return null;
+					}
+					if ($passedVerdict->no()) {
+						$certain = true;
+					}
 				}
 			}
 

tests/PHPStan/Rules/Pure/PureFunctionRuleTest.php

@@ -327,23 +327,24 @@ public function testPureUnlessCallableIsImpurePhp84(): void
 		]);
 	}
 
+	#[RequiresPhp('>= 8.1.0')]
 	public function testPureUnlessParameterPassed(): void
 	{
 		$this->analyse([__DIR__ . '/data/pure-unless-parameter-passed.php'], [
 			[
-				'Possibly impure call to function PureUnlessParameterPassedFunction\myReplace() in pure function PureUnlessParameterPassedFunction\purePassingByRef().',
+				'Impure call to function PureUnlessParameterPassedFunction\myReplace() in pure function PureUnlessParameterPassedFunction\purePassingByRef().',
 				44,
 			],
 			[
-				'Possibly impure call to function PureUnlessParameterPassedFunction\myReplacePhpstanAlias() in pure function PureUnlessParameterPassedFunction\purePassingByRefAlias().',
+				'Impure call to function PureUnlessParameterPassedFunction\myReplacePhpstanAlias() in pure function PureUnlessParameterPassedFunction\purePassingByRefAlias().',
 				62,
 			],
 			[
 				'Possibly impure call to function PureUnlessParameterPassedFunction\myReplace() in pure function PureUnlessParameterPassedFunction\pureUnpackingArgs().',
 				72,
 			],
 			[
-				'Possibly impure call to function PureUnlessParameterPassedFunction\myReplace() in pure function PureUnlessParameterPassedFunction\pureNamedArgForFlaggedParameter().',
+				'Impure call to function PureUnlessParameterPassedFunction\myReplace() in pure function PureUnlessParameterPassedFunction\pureNamedArgForFlaggedParameter().',
 				91,
 			],
 			[
@@ -354,18 +355,42 @@ public function testPureUnlessParameterPassed(): void
 				'Possibly impure call to method PureUnlessParameterPassedFunction\PureUnlessParameterPassedA::m() in pure function PureUnlessParameterPassedFunction\pureUnionMethodPassingCount().',
 				167,
 			],
+			[
+				'Impure call to method PureUnlessParameterPassedFunction\PureUnlessParameterPassedIntersectionA::m() in pure function PureUnlessParameterPassedFunction\pureIntersectionMethodPassingCount().',
+				206,
+			],
+			[
+				'Impure call to method PureUnlessParameterPassedFunction\Replacer::replace() in pure function PureUnlessParameterPassedFunction\pureCallingMethodPassingByRef().',
+				241,
+			],
+			[
+				'Impure call to method PureUnlessParameterPassedFunction\InheritedReplacerChild::replace() in pure function PureUnlessParameterPassedFunction\pureCallingInheritedMethodPassingByRef().',
+				297,
+			],
+			[
+				'Impure call to method PureUnlessParameterPassedFunction\InheritedReplacerRenamedChild::replace() in pure function PureUnlessParameterPassedFunction\pureCallingRenamedInheritedMethodPassingByRef().',
+				318,
+			],
+			[
+				'Possibly impure call to function PureUnlessParameterPassedFunction\myReplace() in pure function PureUnlessParameterPassedFunction\pureCallingFirstClassCallableOmittingCount().',
+				331,
+			],
+			[
+				'Possibly impure call to function PureUnlessParameterPassedFunction\myReplace() in pure function PureUnlessParameterPassedFunction\pureCallingFirstClassCallablePassingCount().',
+				343,
+			],
 		]);
 	}
 
 	public function testPureUnlessParameterPassedBuiltin(): void
 	{
 		$this->analyse([__DIR__ . '/data/pure-unless-parameter-passed-builtin.php'], [
 			[
-				'Possibly impure call to function str_replace() in pure function PureUnlessParameterPassedBuiltin\pureStrReplaceWithCount().',
+				'Impure call to function str_replace() in pure function PureUnlessParameterPassedBuiltin\pureStrReplaceWithCount().',
 				22,
 			],
 			[
-				'Possibly impure call to function preg_match() in pure function PureUnlessParameterPassedBuiltin\purePregMatchWithMatches().',
+				'Impure call to function preg_match() in pure function PureUnlessParameterPassedBuiltin\purePregMatchWithMatches().',
 				40,
 			],
 		]);

tests/PHPStan/Rules/Pure/data/pure-unless-parameter-passed-builtin.php

@@ -16,7 +16,7 @@ function pureStrReplaceWithoutCount(string $s): string
  */
 function pureStrReplaceWithCount(string $s): string
 {
-	// The by-ref $count is passed, so str_replace() is possibly impure.
+	// The by-ref $count is passed, so str_replace() is impure (the flag is certain).
 	$count = 0;
 
 	return str_replace('a', 'b', $s, $count);
@@ -36,6 +36,6 @@ function purePregMatchWithoutMatches(string $s): int
  */
 function purePregMatchWithMatches(string $s): int
 {
-	// The by-ref $matches is passed, so preg_match() is possibly impure.
+	// The by-ref $matches is passed, so preg_match() is impure (the flag is certain).
 	return (int) preg_match('/a/', $s, $matches);
 }

tests/PHPStan/Rules/Pure/data/pure-unless-parameter-passed.php

@@ -1,4 +1,4 @@
-<?php // lint >= 8.0
+<?php // lint >= 8.1
 
 namespace PureUnlessParameterPassedFunction;
 
@@ -38,7 +38,7 @@ function pureNotPassingByRef(string $s): string
  */
 function purePassingByRef(string $s): string
 {
-	// $count is passed, so myReplace() is possibly impure.
+	// $count is passed, so myReplace() is impure (the flag is certain).
 	$count = 0;
 
 	return myReplace($s, $count);
@@ -166,3 +166,179 @@ function pureUnionMethodPassingCount($obj, string $s): string
 	// $count is passed against the Maybe-flagged parameter, so this is possibly impure.
 	return $obj->m($s, $count);
 }
+
+interface PureUnlessParameterPassedIntersectionA
+{
+
+	/**
+	 * @param-out int $count
+	 * @pure-unless-parameter-passed $count
+	 */
+	public function m(string $s, int &$count = 0): string;
+
+}
+
+interface PureUnlessParameterPassedIntersectionB
+{
+
+	public function n(): string;
+
+}
+
+/**
+ * @param PureUnlessParameterPassedIntersectionA&PureUnlessParameterPassedIntersectionB $obj
+ * @phpstan-pure
+ */
+function pureIntersectionMethodOmittingCount($obj, string $s): string
+{
+	// $count is omitted here, so the call stays pure.
+	return $obj->m($s);
+}
+
+/**
+ * @param PureUnlessParameterPassedIntersectionA&PureUnlessParameterPassedIntersectionB $obj
+ * @phpstan-pure
+ */
+function pureIntersectionMethodPassingCount($obj, string $s): string
+{
+	$count = 0;
+	// $count is passed, so this is impure (the flag is certain).
+	return $obj->m($s, $count);
+}
+
+class Replacer
+{
+
+	/**
+	 * @param-out int $count
+	 * @pure-unless-parameter-passed $count
+	 */
+	public function replace(string $subject, int &$count = 0): string
+	{
+		$count = 1;
+
+		return $subject;
+	}
+
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureCallingMethodNotPassingByRef(Replacer $replacer, string $s): string
+{
+	// $count is omitted, so the call stays pure.
+	return $replacer->replace($s);
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureCallingMethodPassingByRef(Replacer $replacer, string $s): string
+{
+	$count = 0;
+	// $count is passed, so the call is impure (the flag is certain).
+	return $replacer->replace($s, $count);
+}
+
+abstract class InheritedReplacerParent
+{
+
+	/**
+	 * @param-out int $count
+	 * @pure-unless-parameter-passed $count
+	 */
+	abstract public function replace(string $subject, int &$count = 0): string;
+
+}
+
+class InheritedReplacerChild extends InheritedReplacerParent
+{
+
+	public function replace(string $subject, int &$count = 0): string
+	{
+		$count = 1;
+
+		return $subject;
+	}
+
+}
+
+class InheritedReplacerRenamedChild extends InheritedReplacerParent
+{
+
+	public function replace(string $subject, int &$cnt = 0): string
+	{
+		$cnt = 1;
+
+		return $subject;
+	}
+
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureCallingInheritedMethodNotPassingByRef(InheritedReplacerChild $replacer, string $s): string
+{
+	// The child does not re-declare @pure-unless-parameter-passed; it is inherited
+	// from the parent. $count is omitted here, so the call stays pure.
+	return $replacer->replace($s);
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureCallingInheritedMethodPassingByRef(InheritedReplacerChild $replacer, string $s): string
+{
+	$count = 0;
+	// The inherited @pure-unless-parameter-passed applies to the child, so passing
+	// $count makes the call impure (the flag is certain).
+	return $replacer->replace($s, $count);
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureCallingRenamedInheritedMethodNotPassingByRef(InheritedReplacerRenamedChild $replacer, string $s): string
+{
+	// The parent flags $count; the child renames it to $cnt. The inherited flag
+	// still applies to the renamed parameter. It is omitted here, so this stays pure.
+	return $replacer->replace($s);
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureCallingRenamedInheritedMethodPassingByRef(InheritedReplacerRenamedChild $replacer, string $s): string
+{
+	$cnt = 0;
+	// The inherited flag applies to the renamed parameter, so passing it makes
+	// the call impure (the flag is certain).
+	return $replacer->replace($s, $cnt);
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureCallingFirstClassCallableOmittingCount(string $s): string
+{
+	$f = myReplace(...);
+	// A first-class callable's purity is evaluated from its ParametersAcceptor
+	// alone, without scope/args, so @pure-unless-parameter-passed cannot gate on
+	// whether $count is actually passed at this call site; it stays possibly
+	// impure even though $count is omitted here.
+	return $f($s);
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureCallingFirstClassCallablePassingCount(string $s): string
+{
+	$count = 0;
+	$f = myReplace(...);
+	// The first-class callable is called with the flagged $count passed, so this
+	// stays possibly impure.
+	return $f($s, $count);
+}