Leave the PCRE functions out of @pure-unless-parameter-passed

preg_match(), preg_match_all(), preg_replace() and preg_filter() raise a
warning on an invalid pattern and set preg_last_error(), so they are not
pure even when their out parameter is omitted. Code relies on that: a bare
preg_match($pattern, '') under set_error_handler() validates a pattern.
preg_replace_callback() goes back to its callback-only entry.

No built-in carries both conditions any more, so a userland function
tagged with both covers the combined verdict.

Author: zonuexe

bin/functionMetadata_original.php

@@ -18,8 +18,7 @@
  *         (keyed by parameter name) receives an argument, e.g. str_replace()
  *         whose only side effect is writing to its optional 'count' argument.
  *
- * The last two can be combined for a call that is pure unless either happens,
- * e.g. preg_replace_callback() (impure callback or a passed 'count').
+ * The last two can be combined for a call that is pure unless either happens.
  */
 
 /** @var array<string, array{hasSideEffects?: bool, pureUnlessCallableIsImpureParameters?: array<string, bool>, pureUnlessParameterPassedParameters?: array<string, bool>}> */
@@ -271,13 +270,7 @@
 	'output_reset_rewrite_vars' => ['hasSideEffects' => true],
 	'pclose' => ['hasSideEffects' => true],
 	'popen' => ['hasSideEffects' => true],
-	'preg_filter' => ['pureUnlessParameterPassedParameters' => ['count' => true]],
-	// 'matches'/'subpatterns': PHP 8+ uses the php-8-stubs parameter name, PHP <8 falls
-	// back to the legacy functionMap.php name.
-	'preg_match' => ['pureUnlessParameterPassedParameters' => ['matches' => true, 'subpatterns' => true]],
-	'preg_match_all' => ['pureUnlessParameterPassedParameters' => ['matches' => true, 'subpatterns' => true]],
-	'preg_replace' => ['pureUnlessParameterPassedParameters' => ['count' => true]],
-	'preg_replace_callback' => ['pureUnlessCallableIsImpureParameters' => ['callback' => true], 'pureUnlessParameterPassedParameters' => ['count' => true]],
+	'preg_replace_callback' => ['pureUnlessCallableIsImpureParameters' => ['callback' => true]],
 	'similar_text' => ['pureUnlessParameterPassedParameters' => ['percent' => true]],
 	'readfile' => ['hasSideEffects' => true],
 	'rename' => ['hasSideEffects' => true],

resources/functionMetadata.php

@@ -1633,15 +1633,11 @@
 	'posix_ttyname' => ['hasSideEffects' => false],
 	'posix_uname' => ['hasSideEffects' => false],
 	'pow' => ['hasSideEffects' => false],
-	'preg_filter' => ['pureUnlessParameterPassedParameters' => ['count' => true]],
 	'preg_grep' => ['hasSideEffects' => false],
 	'preg_last_error' => ['hasSideEffects' => true],
 	'preg_last_error_msg' => ['hasSideEffects' => true],
-	'preg_match' => ['pureUnlessParameterPassedParameters' => ['matches' => true, 'subpatterns' => true]],
-	'preg_match_all' => ['pureUnlessParameterPassedParameters' => ['matches' => true, 'subpatterns' => true]],
 	'preg_quote' => ['hasSideEffects' => false],
-	'preg_replace' => ['pureUnlessParameterPassedParameters' => ['count' => true]],
-	'preg_replace_callback' => ['pureUnlessCallableIsImpureParameters' => ['callback' => true], 'pureUnlessParameterPassedParameters' => ['count' => true]],
+	'preg_replace_callback' => ['pureUnlessCallableIsImpureParameters' => ['callback' => true]],
 	'preg_split' => ['hasSideEffects' => false],
 	'property_exists' => ['hasSideEffects' => false],
 	'quoted_printable_decode' => ['hasSideEffects' => false],

src/Reflection/Callables/SimpleImpurePoint.php

@@ -137,9 +137,9 @@ public static function createFromVariant(FunctionReflection|ExtendedMethodReflec
 	}
 
 	/**
-	 * A function can carry both flags at once (e.g. preg_replace_callback, which is
-	 * pure unless its callback is impure or its $count is passed), so the two
-	 * verdicts are combined. Returns null when the variant declares neither flag.
+	 * A function can carry both flags at once (pure unless a callback is impure
+	 * or an out parameter is passed), so the two verdicts are combined. Returns
+	 * null when the variant declares neither flag.
 	 *
 	 * @param Arg[] $args
 	 */

tests/PHPStan/Rules/Pure/PureFunctionRuleTest.php

@@ -488,51 +488,55 @@ public function testPureUnlessParameterPassed(): void
 				'Impure echo in pure function PureUnlessParameterPassedFunction\sideEffectUnlessParameterPassed().',
 				470,
 			],
-		]);
-	}
-
-	public function testPureUnlessParameterPassedBuiltin(): void
-	{
-		$this->analyse([__DIR__ . '/data/pure-unless-parameter-passed-builtin.php'], [
 			[
-				'Impure call to function str_replace() in pure function PureUnlessParameterPassedBuiltin\pureStrReplaceWithCount().',
-				22,
+				'Impure call to function PureUnlessParameterPassedFunction\myReplaceCallback() in pure function PureUnlessParameterPassedFunction\pureBothPureCallbackPassingCount().',
+				505,
 			],
 			[
-				'Impure call to function preg_match() in pure function PureUnlessParameterPassedBuiltin\purePregMatchWithMatches().',
-				40,
+				'Impure call to function PureUnlessParameterPassedFunction\myReplaceCallback() in pure function PureUnlessParameterPassedFunction\pureBothImpureCallbackOmittingCount().',
+				514,
 			],
 			[
-				'Impure call to function preg_filter() in pure function PureUnlessParameterPassedBuiltin\purePregFilterWithCount().',
-				60,
+				'Impure echo in pure function PureUnlessParameterPassedFunction\pureBothImpureCallbackOmittingCount().',
+				515,
 			],
 			[
-				'Impure call to function preg_replace_callback() in pure function PureUnlessParameterPassedBuiltin\purePregReplaceCallbackWithCount().',
-				80,
+				'Possibly impure call to a callable in pure function PureUnlessParameterPassedFunction\pureBothOpaqueCallbackOmittingCount().',
+				528,
 			],
 			[
-				'Impure call to function preg_replace_callback() in pure function PureUnlessParameterPassedBuiltin\purePregReplaceCallbackImpureCallback().',
-				89,
+				'Possibly impure call to function PureUnlessParameterPassedFunction\myReplaceCallback() in pure function PureUnlessParameterPassedFunction\pureBothOpaqueCallbackOmittingCount().',
+				528,
 			],
 			[
-				'Impure echo in pure function PureUnlessParameterPassedBuiltin\purePregReplaceCallbackImpureCallback().',
-				90,
+				'Impure call to function PureUnlessParameterPassedFunction\myReplaceCallback() in pure function PureUnlessParameterPassedFunction\pureBothOpaqueCallbackPassingCount().',
+				539,
 			],
 			[
-				'Impure call to function str_ireplace() in pure function PureUnlessParameterPassedBuiltin\pureStrIreplaceWithCount().',
-				113,
+				'Possibly impure call to a callable in pure function PureUnlessParameterPassedFunction\pureBothOpaqueCallbackPassingCount().',
+				539,
 			],
+		]);
+	}
+
+	public function testPureUnlessParameterPassedBuiltin(): void
+	{
+		$this->analyse([__DIR__ . '/data/pure-unless-parameter-passed-builtin.php'], [
 			[
-				'Impure call to function preg_replace() in pure function PureUnlessParameterPassedBuiltin\purePregReplaceWithCount().',
-				133,
+				'Impure call to function str_replace() in pure function PureUnlessParameterPassedBuiltin\pureStrReplaceWithCount().',
+				22,
 			],
 			[
-				'Impure call to function preg_match_all() in pure function PureUnlessParameterPassedBuiltin\purePregMatchAllWithMatches().',
-				151,
+				'Possibly impure call to function preg_match() in pure function PureUnlessParameterPassedBuiltin\purePregMatchWithoutMatches().',
+				32,
+			],
+			[
+				'Impure call to function str_ireplace() in pure function PureUnlessParameterPassedBuiltin\pureStrIreplaceWithCount().',
+				52,
 			],
 			[
 				'Impure call to function similar_text() in pure function PureUnlessParameterPassedBuiltin\pureSimilarTextWithPercent().',
-				169,
+				70,
 			],
 		]);
 	}

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

@@ -27,72 +27,11 @@ function pureStrReplaceWithCount(string $s): string
  */
 function purePregMatchWithoutMatches(string $s): int
 {
-	// The by-ref $matches is omitted, so preg_match() is pure.
+	// preg_match() is left out of the metadata even with $matches omitted: an invalid
+	// pattern raises a warning and sets preg_last_error(), so the call stays possibly impure.
 	return (int) preg_match('/a/', $s);
 }
 
-/**
- * @phpstan-pure
- */
-function purePregMatchWithMatches(string $s): int
-{
-	// The by-ref $matches is passed, so preg_match() is impure (the flag is certain).
-	return (int) preg_match('/a/', $s, $matches);
-}
-
-/**
- * @phpstan-pure
- */
-function purePregFilterWithoutCount(string $s): ?string
-{
-	// The by-ref $count is omitted, so preg_filter() is pure.
-	return preg_filter('/a/', 'b', $s);
-}
-
-/**
- * @phpstan-pure
- */
-function purePregFilterWithCount(string $s): ?string
-{
-	// The by-ref $count is passed, so preg_filter() is impure (the flag is certain).
-	$count = 0;
-
-	return preg_filter('/a/', 'b', $s, -1, $count);
-}
-
-/**
- * @phpstan-pure
- */
-function purePregReplaceCallbackPureCallback(string $s): ?string
-{
-	// preg_replace_callback() carries both flags: the callback is pure and the by-ref
-	// $count is omitted, so the call stays pure.
-	return preg_replace_callback('/a/', static fn (array $m): string => $m[0], $s);
-}
-
-/**
- * @phpstan-pure
- */
-function purePregReplaceCallbackWithCount(string $s): ?string
-{
-	$count = 0;
-	// The callback is pure but the by-ref $count is passed, so the call is impure.
-	return preg_replace_callback('/a/', static fn (array $m): string => $m[0], $s, -1, $count);
-}
-
-/**
- * @phpstan-pure
- */
-function purePregReplaceCallbackImpureCallback(string $s): ?string
-{
-	// The callback itself is impure, so the call is impure regardless of $count.
-	return preg_replace_callback('/a/', static function (array $m): string {
-		echo $m[0];
-
-		return $m[0];
-	}, $s);
-}
-
 /**
  * @phpstan-pure
  */
@@ -113,44 +52,6 @@ function pureStrIreplaceWithCount(string $s): string
 	return str_ireplace('a', 'b', $s, $count);
 }
 
-/**
- * @phpstan-pure
- */
-function purePregReplaceWithoutCount(string $s): ?string
-{
-	// The by-ref $count is omitted, so preg_replace() is pure.
-	return preg_replace('/a/', 'b', $s);
-}
-
-/**
- * @phpstan-pure
- */
-function purePregReplaceWithCount(string $s): ?string
-{
-	// The by-ref $count is passed, so preg_replace() is impure (the flag is certain).
-	$count = 0;
-
-	return preg_replace('/a/', 'b', $s, -1, $count);
-}
-
-/**
- * @phpstan-pure
- */
-function purePregMatchAllWithoutMatches(string $s): int
-{
-	// The by-ref $matches is omitted, so preg_match_all() is pure.
-	return (int) preg_match_all('/a/', $s);
-}
-
-/**
- * @phpstan-pure
- */
-function purePregMatchAllWithMatches(string $s): int
-{
-	// The by-ref $matches is passed, so preg_match_all() is impure (the flag is certain).
-	return (int) preg_match_all('/a/', $s, $matches);
-}
-
 /**
  * @phpstan-pure
  */

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

@@ -472,3 +472,69 @@ function sideEffectUnlessParameterPassed(string $subject, int &$count = 0): stri
 
 	return $subject;
 }
+
+/**
+ * @param callable(string): string $f
+ * @param-out int $count
+ * @pure-unless-callable-is-impure $f
+ * @pure-unless-parameter-passed $count
+ */
+function myReplaceCallback(callable $f, string $subject, int &$count = 0): string
+{
+	$count = 1;
+
+	return $f($subject);
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureBothConditionsMet(string $s): string
+{
+	// The callback is pure and $count is omitted, so the call stays pure.
+	return myReplaceCallback(static fn (string $x): string => $x, $s);
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureBothPureCallbackPassingCount(string $s): string
+{
+	$count = 0;
+	// The callback is pure but $count is passed, so the call is impure.
+	return myReplaceCallback(static fn (string $x): string => $x, $s, $count);
+}
+
+/**
+ * @phpstan-pure
+ */
+function pureBothImpureCallbackOmittingCount(string $s): string
+{
+	// $count is omitted but the callback is impure, so the call is impure.
+	return myReplaceCallback(static function (string $x): string {
+		echo $x;
+
+		return $x;
+	}, $s);
+}
+
+/**
+ * @param callable(string): string $f
+ * @phpstan-pure
+ */
+function pureBothOpaqueCallbackOmittingCount(callable $f, string $s): string
+{
+	// $count is omitted but the callback's purity is unknown, so the call stays possibly impure.
+	return myReplaceCallback($f, $s);
+}
+
+/**
+ * @param callable(string): string $f
+ * @phpstan-pure
+ */
+function pureBothOpaqueCallbackPassingCount(callable $f, string $s): string
+{
+	$count = 0;
+	// $count is passed, so the call is impure whatever the callback does.
+	return myReplaceCallback($f, $s, $count);
+}

turbo-ext/tests/type-family.php

@@ -6890,7 +6890,7 @@ public function getResolvedPhpDoc(): ?\PHPStan\PhpDoc\ResolvedPhpDocBlock { retu
 // arguments), the pure-unless-callable-is-impure parameters of array_filter()
 // and array_reduce() fed pure, impure, maybe-pure, null, non-callable and
 // omitted callbacks (positional and named), the pure-unless-parameter-passed
-// out parameters of str_replace() and preg_match() passed and omitted
+// out parameters of str_replace() and similar_text() passed and omitted
 // (positional, named and unpacked), both verdicts combined and applied to a
 // keyed list of certain and uncertain points, the transformed and plain
 // fixture methods, a missing scope or variant, and unconstructed instances
@@ -6931,10 +6931,11 @@ public function getResolvedPhpDoc(): ?\PHPStan\PhpDoc\ResolvedPhpDocBlock { retu
 		'named count' => [$arg('string'), $arg('string'), $arg('string'), $arg('true', 'count')],
 		'named matches' => [$arg('string', 'pattern'), $arg('string', 'subject'), $arg('true', 'matches')],
 		'named subject only' => [$arg('string', 'pattern'), $arg('string', 'subject')],
+		'named percent' => [$arg('string', 'string1'), $arg('string', 'string2'), $arg('true', 'percent')],
 		'unpacked' => [new \PhpParser\Node\Arg(new \PhpParser\Node\Expr\Variable('array'), unpack: true)],
 	];
 	$functions = [];
-	foreach (['strlen', 'usleep', 'print_r', 'var_export', 'highlight_string', 'array_filter', 'array_reduce', 'array_map', 'rand', 'str_replace', 'preg_match'] as $functionName) {
+	foreach (['strlen', 'usleep', 'print_r', 'var_export', 'highlight_string', 'array_filter', 'array_reduce', 'array_map', 'rand', 'str_replace', 'similar_text'] as $functionName) {
 		$functions[$functionName] = $stringReflectionProvider->getFunction(new \PhpParser\Node\Name($functionName), null);
 	}
 	foreach ($functions as $functionName => $function) {