Implement @pure-unless-callable-is-impure by zonuexe · Pull Request #3482 · phpstan/phpstan-src

zonuexe · 2024-09-25T17:46:00Z

Implements the @pure-unless-callable-is-impure PHPDoc tag (parser support: phpstan/phpdoc-parser#253, merged): a parameter-level annotation declaring that the function/method is pure unless the callable passed to that parameter is impure. Rebuilt on top of 2.2.x.

How it works

The tag (and its @phpstan- prefixed alias) is resolved into per-parameter flags, threaded through the reflection layer (ExtendedParameterReflection::isPureUnlessCallableIsImpureParameter()), and populated for builtins via functionMetadata (array_filter, array_map, array_reduce, the array_*u* comparator family, call_user_func(_array), forward_static_call(_array), preg_replace_callback(_array), …) and for array_reduce via its stub.
SimpleImpurePoint::createFromVariant() evaluates the purity of arguments passed to flagged parameters:
- provably pure callback (or omitted / null) → no impure point — the call is treated as pure;
- provably impure callback → the impure point becomes certain;
- unknown callable (opaque callable type) → unchanged possibly-impure behavior.
Since the no-effect detection (NoopExpressionNode) is driven by "the statement has zero impure points", standalone array_map($pureCb, $arr); statements are now reported by CallToFunctionStatementWithoutSideEffectsRule with no rule changes.

/** @phpstan-pure */
function doubled(array $arr): array
{
    return array_map(static fn (int $x): int => $x * 2, $arr); // no longer "Possibly impure"
}

array_map('is_string', $arr); // now: "Call to function array_map() on a separate line has no effect."
array_map(static function ($x) { echo $x; }, $arr); // still allowed as a statement (impure callback)

Add function map
Add tests (fail-first: PureFunctionRule/PureMethodRule regressions, CallToFunctionStatementWithoutSideEffectsRule cases incl. impure/opaque/by-ref non-regressions)
Add rules (no new rule needed — the impure-point suppression feeds both the pure-context check and the existing no-effect rule)

refs #3106, #5912

Closes phpstan/phpstan#11101
Closes phpstan/phpstan#11100

zonuexe · 2024-09-25T17:48:51Z

Will be replaced by phpstan/phpdoc-parser#253

zonuexe · 2024-09-25T17:52:43Z

WIP. = false will be removed.

ondrejmirtes · 2024-09-26T07:30:39Z

Just updated phpdoc-parser here so you can use that.

staabm · 2024-11-18T15:43:16Z

@zonuexe any plans to move this forward?

zonuexe · 2024-11-19T16:50:46Z

@staabm Hi, I know this branch is important but it was blocked due to my motivation. I'm going to rebase it on 2.0.x and do the necessary work. If I miss it tonight, I won't be able to start the rest of the work until next week, so it would be quicker for you to take over then.

staabm · 2024-11-19T16:53:12Z

I don't want to put pressure on you. It was not clear to me whether you stopped working on it or not.

I am totally fine if this takes a bit more time - thank you

zonuexe · 2024-11-19T17:03:44Z

No problem, this is a very interesting subject for me too, so I'm happy to work on it because I realized that there are other people who are interested in it. More importantly, I'm always helped by your hard work.

VincentLanglet · 2025-07-20T11:37:21Z

Friendly ping @zonuexe, still interested in this PR ? Do you have time to finish it ?
Do you look for help ? What is missing ?

zonuexe · 2025-07-20T12:21:33Z

@VincentLanglet
Thank you for the suggestion, sorry for making you wait so long.
I've been working on PHPStan 2.1.18 a few times over the last few weeks, and just finished a PHPStan workshop at a local PHP conference, so I'll get back to that tomorrow.

VincentLanglet · 2025-10-07T09:05:49Z

Friendly ping @zonuexe

I don't want to put pressure on you. It's just not clear to me whether you stopped working on it or not.
What is missing ?

It will unblock the phpstan/phpdoc-parser#259 pr :)

VincentLanglet · 2026-05-01T21:53:21Z

Maybe I'm wrong, but I start to think this annotation is useless
https://phpstan.org/r/d3af976b-17ef-4ca6-87cb-4a1325622cee

PHPStan already handle cb with immediately/later invoked callable, even for a pure function/method.

So we just need to declare array_map and so as pure.

devbanana · 2026-05-04T02:42:56Z

i'm happy to help contribute towards a solution if it's decided which direction is best.

VincentLanglet · 2026-05-06T18:47:03Z

Hi @devbanana feel free to work on this.

Laybe @zonuexe could explain what he had in mind ; or @ondrejmirtes will have some guidelines

phpstan-bot · 2026-07-03T08:49:07Z

This pull request has been marked as ready for review.

staabm · 2026-07-05T05:52:19Z


+	public function getPureUnlessCallableIsImpureParameters(): array
+	{
+		return [];


Suggested change

return [];

return $this->reflection->getPureUnlessCallableIsImpureParameters();

(seems we miss a test)

staabm · 2026-07-05T05:55:04Z


+	public function getPureUnlessCallableIsImpureParameters(): array
+	{
+		return [];


Suggested change

return [];

return $this->nativeMethodReflection->getPureUnlessCallableIsImpureParameters();

staabm · 2026-07-05T05:56:24Z


+	public function getPureUnlessCallableIsImpureParameters(): array
+	{
+		return [];


hmm does this miss the impl?

staabm · 2026-07-05T05:58:19Z


+	public function getPureUnlessCallableIsImpureParameters(): array
+	{
+		return [];


what about this?

staabm · 2026-07-05T05:58:29Z


+	public function getPureUnlessCallableIsImpureParameters(): array
+	{
+		return [];


staabm · 2026-07-05T08:01:18Z

 		return TrinaryLogic::createYes();
 	}

+	public function getPureUnlessCallableIsImpureParameters(): array


also needs tests with constructor

Good catch. You were right that method support was entirely non-functional, not only those stubs. Two gaps caused it.

PhpClassReflectionExtension read the pure-unless map only from built-in method metadata, never from a userland method's own @pure-unless-callable-is-impure tag.

PhpMethodReflection::getParameters() did not pass the flag on to PhpParameterReflection, while the function path already did.

I fixed both and made the wrappers you pointed at delegate. I also added a method regression test with pure, impure and opaque callbacks, including a union-typed receiver.

zonuexe · 2026-07-05T08:13:28Z

Follow-up on method support.

Method-level @pure-unless-callable-is-impure now works end to end, at parity with functions. Verified for direct, union-typed and intersection-typed receivers.
I audited every parameter-construction site for the same flag-dropping pattern. The others are correct, because the instanceof ExtendedParameterReflection ? ... : new ExtendedDummyParameter(...) wraps only ever see non-extended parameters, which cannot carry the flag.
Two paths stay un-threaded on purpose and now carry a comment: createNativeMethodVariant(), since no built-in method carries the metadata, and Closure::call()'s own parameters, since a closure cannot carry the tag.

phpstan-bot · 2026-07-05T08:14:44Z

This pull request has been marked as ready for review.

Resolve the tag into per-parameter flags and merge them across parent PHPDocs.

Add isPureUnlessCallableIsImpureParameter() on parameter reflections and getPureUnlessCallableIsImpureParameters() on function/method reflections, populated from PHPDoc and function metadata.

Return the parameter flags from getPhpDocs(), thread them through enterClassMethod(), and consult them when collecting impure points for calls.

array_filter/array_map/array_reduce, the array_u*/array_*_u* family, call_user_func(_array), forward_static_call(_array) and preg_replace_callback(_array) are pure unless their callback argument is impure.

Type-inference fixture plus function-metadata expectations.

The flag was silently dropped wherever parameters are re-wrapped (combineAcceptors, overrideParameterType, resolved template variants, unresolved method prototypes) and the BetterReflection function path never read the PHPDoc tag. Also honor the @phpstan- prefixed alias, strip the leading $ from the tag's parameter name, read the tag from stub PHPDocs, and annotate array_reduce's stub.

…acks are pure SimpleImpurePoint::createFromVariant() now evaluates the purity of arguments passed to flagged parameters: provably pure (or omitted) callbacks produce no impure point, provably impure ones make the point certain, unknown callables keep the current possibly-impure behavior. This fixes the false positive for array_map() with a pure callback in @phpstan-pure functions and enables the no-effect report for standalone statements. Closes phpstan/phpstan#11100 Closes phpstan/phpstan#11101

Named arguments are not supported by the PHP 7.4 downgrade, so pass the enterClassMethod() parameters positionally. The file-without-errors.php fixture contained a standalone array_filter() call that is now correctly reported as having no effect - wrap it in echo count().

…-callable arguments Kills the two escaped Infection mutants in SimpleImpurePoint: a (callable|null) callback exercises the isNull() branch and a (pure-callable|int) callback exercises the isCallable() branch - both keep the call possibly impure.

Address review nits: use null coalescing for the array<string, bool> parameter flags, a ternary for the hasSideEffects TrinaryLogic (keeping the absent -> Maybe branch), and split the negated method hasSideEffects read into named steps matching the ancestors loop below.

@var

The value shape gained a second form (pureUnlessCallableIsImpureParameters), so describe both forms in the file-level comments of the source, the generator template and the generated file, add an inline @var before the array, and fix the generator's now-stale internal @var.

PHP 8.4's array_all() and array_any() are pure unless their callback is impure, like array_filter()/array_map().

…tions Generic builtins like array_find()/array_find_key() are reflected via BetterReflection (PhpFunctionReflection), whose getCustomFunction() only read the @pure-unless-callable-is-impure PHPDoc tag and ignored functionMetadata.php - unlike the native-signature path. Merge the metadata's pureUnlessCallableIsImpureParameters in there too (PHPDoc tag wins). This makes array_find() actually honor its existing metadata entry and lets array_find_key() be added.

RequiredPhpVersionCommentTest requires fixtures using version-specific features to declare a '// lint >= X.Y' comment so they are skipped on older PHP in CI.

Method support was entirely non-functional: PhpClassReflectionExtension only read the pure-unless map from built-in method metadata (never from a userland method's own PHPDoc tag), and PhpMethodReflection::getParameters() never passed the flag on to its PhpParameterReflection (the function path already did). Read the tag from the resolved PHPDoc and thread the flag through, and make the method-reflection wrappers (changed-type, closure-call, intersection, union, parser-node function) delegate getPureUnlessCallableIsImpureParameters() instead of returning [].

createNativeMethodVariant() (no built-in method carries the metadata) and Closure::call()'s parameters (a closure cannot carry the tag) leave the flag at its default; document why so a future maintainer knows it is deliberate, not an oversight.

zonuexe marked this pull request as draft September 25, 2024 17:46

zonuexe commented Sep 25, 2024

View reviewed changes

Comment thread src/PhpDoc/PhpDocNodeResolver.php Outdated

zonuexe Sep 25, 2024

Copy link
Copy Markdown

Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will be replaced by phpstan/phpdoc-parser#253

zonuexe commented Sep 25, 2024

View reviewed changes

zonuexe force-pushed the feature/pure-unless-callable-is-impure branch 4 times, most recently from eddd22a to f207c72 Compare September 30, 2024 18:09

zonuexe force-pushed the feature/pure-unless-callable-is-impure branch from f207c72 to 8c756cc Compare November 3, 2024 17:57

zonuexe force-pushed the feature/pure-unless-callable-is-impure branch from 8c756cc to 389c7f0 Compare November 19, 2024 16:58

zonuexe changed the base branch from 1.12.x to 2.0.x November 19, 2024 17:11

zonuexe force-pushed the feature/pure-unless-callable-is-impure branch 4 times, most recently from 2146ae0 to 1cc1fad Compare November 19, 2024 18:32

ondrejmirtes mentioned this pull request Jan 15, 2025

Support for @pure-unless-parameter-passed phpstan/phpdoc-parser#259

Open

zonuexe force-pushed the feature/pure-unless-callable-is-impure branch from adb02ca to abc8cd8 Compare August 1, 2025 12:45

zonuexe changed the base branch from 2.0.x to 2.1.x August 1, 2025 12:46

zonuexe force-pushed the feature/pure-unless-callable-is-impure branch from abc8cd8 to c4999be Compare August 1, 2025 13:09

staabm mentioned this pull request May 1, 2026

A method with @phpstan-pure Cannot Call Array Callback Functions Like array_filter, Even If the Callback Is Pure phpstan/phpstan#14562

Closed

zonuexe marked this pull request as ready for review July 3, 2026 08:48

staabm requested a review from VincentLanglet July 3, 2026 09:52

VincentLanglet approved these changes Jul 4, 2026

View reviewed changes

VincentLanglet requested review from ondrejmirtes and staabm July 4, 2026 19:02

staabm approved these changes Jul 4, 2026

View reviewed changes

staabm reviewed Jul 5, 2026

View reviewed changes

zonuexe marked this pull request as draft July 5, 2026 07:36

staabm reviewed Jul 5, 2026

View reviewed changes

zonuexe marked this pull request as ready for review July 5, 2026 08:13

zonuexe added 16 commits July 5, 2026 17:18

Parse @pure-unless-callable-is-impure PHPDoc tag

b93ad8b

Resolve the tag into per-parameter flags and merge them across parent PHPDocs.

Thread pure-unless-callable-is-impure through the reflection layer

b103f39

Add isPureUnlessCallableIsImpureParameter() on parameter reflections and getPureUnlessCallableIsImpureParameters() on function/method reflections, populated from PHPDoc and function metadata.

Wire pure-unless-callable-is-impure into the analyser

83ab4a7

Return the parameter flags from getPhpDocs(), thread them through enterClassMethod(), and consult them when collecting impure points for calls.

Mark callback-accepting builtins as pure-unless-callable-is-impure

14dbc2c

array_filter/array_map/array_reduce, the array_u*/array_*_u* family, call_user_func(_array), forward_static_call(_array) and preg_replace_callback(_array) are pure unless their callback argument is impure.

Add tests for @pure-unless-callable-is-impure

cc3c0a8

Type-inference fixture plus function-metadata expectations.

Mark array_all() and array_any() as pure-unless-callable-is-impure

e3e4b6a

PHP 8.4's array_all() and array_any() are pure unless their callback is impure, like array_filter()/array_map().

Add lint version comment to the PHP 8.4 pure-unless fixture

e7c4b29

RequiredPhpVersionCommentTest requires fixtures using version-specific features to declare a '// lint >= X.Y' comment so they are skipped on older PHP in CI.

zonuexe force-pushed the feature/pure-unless-callable-is-impure branch from 0188553 to c45ca89 Compare July 5, 2026 08:20

	return [];
	return $this->reflection->getPureUnlessCallableIsImpureParameters();

	return [];
	return $this->nativeMethodReflection->getPureUnlessCallableIsImpureParameters();

Uh oh!

Conversation

zonuexe commented Sep 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How it works

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ondrejmirtes commented Sep 26, 2024

Uh oh!

staabm commented Nov 18, 2024

Uh oh!

zonuexe commented Nov 19, 2024

Uh oh!

staabm commented Nov 19, 2024

Uh oh!

zonuexe commented Nov 19, 2024

Uh oh!

VincentLanglet commented Jul 20, 2025

Uh oh!

zonuexe commented Jul 20, 2025

Uh oh!

VincentLanglet commented Oct 7, 2025

Uh oh!

VincentLanglet commented May 1, 2026

Uh oh!

devbanana commented May 4, 2026

Uh oh!

VincentLanglet commented May 6, 2026

Uh oh!

phpstan-bot commented Jul 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zonuexe commented Jul 5, 2026

Uh oh!

phpstan-bot commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

zonuexe commented Sep 25, 2024 •

edited

Loading