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
{
    // no longer false positive "Possibly impure"
    return array_map(static fn (int $x): int => $x * 2, $arr);
}

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

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

staabm · 2026-07-06T18:46:05Z

 	 */
 	public function checkAllowedConstants(array $constants): AllowedConstantsResult;

+	public function isPureUnlessCallableIsImpureParameter(): bool;


should return trinary.

quoting ondrey:

I feel like on ExtendedParametersAcceptor, the method isPureUnlessCallableIsImpureParameter should return TrinaryLogic.
Because you need to correctly set it on unions and intersection methods

staabm · 2026-07-07T05:06:05Z

+ * @param callable(int): int $f
+ * @param array<int> $arr
+ * @return array<int>
+ * @pure-unless-callable-is-impure $f


we need a test which shows that a function which is declared @pure-unless-callable-is-impure $f errors about impure side-effects when the impure statement/expression is outside the callable $f

staabm · 2026-07-07T05:06:33Z

+ * @param callable(int): int $f
+ * @param array<int> $arr
+ * @return array<int>
+ * @phpstan-pure-unless-callable-is-impure $f


If @pure-unless-callable-is-impure is paired with pure-callable or pure-Closure , that should be a new kind of error (that the PHPdoc tag could be replaced with @phpstan-pure essentially

Per review: the parameter-level flag must be a TrinaryLogic so it composes correctly on union and intersection method variants (combineAcceptors uses ->or(), mirroring isImmediatelyInvokedCallable). Origins convert the bool from PHPDoc/metadata with TrinaryLogic::createFromBoolean(); the consumption in SimpleImpurePoint skips only parameters whose flag is ->no().

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.

Per review: when @pure-unless-callable-is-impure $f is paired with a pure callable type (pure-callable / pure-Closure) for $f, the tag is redundant because the callback is always pure, so the function/method can be marked @phpstan-pure instead. FunctionPurityCheck now reports this.

ondrejmirtes

One more thing - in MethodSignatureRule, we need to enforce covariance for these methods. Check around $this->reportMethodPurityOverride.

If a method has @phpstan-pure or @phpstan-pure-unless-callable-is-impure, the child method cannot be @phpstan-impure.

Also are there same tests around @phpstan-pure-unless-callable-is-impure being inherited implicitly? (The child method does not need to mention the parameter but if parent method has it, it should also apply to child. Even when the parameter is renamed.)

ondrejmirtes · 2026-07-07T06:40:20Z

 	public function isPure(): TrinaryLogic;

+	/**
+	 * @return array<string, bool>


Should still be TrinaryLogic here. When you have UnionMethodReflection or IntersectionMethodReflection (and the methods in question have different PHPDoc tags involved, you need TrinaryLogic to properly model the behaviour). Also add some tests.

Per review (ondrejmirtes): the method/function-level map must return array<string, TrinaryLogic> so UnionTypeMethodReflection and IntersectionTypeMethodReflection can model Maybe when constituent methods disagree on the tag (new MergedPureUnlessCallableIsImpureParameters helper). combineAcceptors() now merges the parameter-level flag with equals-or-Maybe instead of ->or(), so a union receiver yields a Maybe flag. FunctionPurityCheck drives its flagged-parameter set off the map getter. Adds union and inherited (incl. renamed-parameter) regression tests.

Per review (ondrejmirtes): MethodSignatureRule now enforces purity covariance for the tag - a child method marked @phpstan-impure cannot override a parent method carrying @pure-unless-callable-is-impure (identifier method.impureOverridePureUnlessCallable), mirroring the existing pure-override check. Gated by reportMethodPurityOverride.

zonuexe · 2026-07-07T07:52:37Z

@ondrejmirtes @staabm Both review points are addressed.

1. TrinaryLogic on the map getter. getPureUnlessCallableIsImpureParameters() now returns array<string, TrinaryLogic> across the interfaces and all implementers. UnionTypeMethodReflection / IntersectionTypeMethodReflection merge their members per parameter (new MergedPureUnlessCallableIsImpureParameters helper) so a parameter tagged in some members but not others becomes Maybe, and combineAcceptors() merges the parameter-level flag with equals-or-Maybe instead of ->or(), so a union receiver yields a real Maybe at the call site. Added union and implicit-inheritance tests (child does not re-declare the tag), including the renamed-parameter case.

2. Purity covariance. MethodSignatureRule now reports a @phpstan-impure child overriding a parent that carries @pure-unless-callable-is-impure (method.impureOverridePureUnlessCallable), gated by reportMethodPurityOverride.

Note: the Mutation Testing job is still red on a few mutants around the verdict/override branches. The tests seem to kill them locally, so I will leave it to you two to decide how to proceed.

phpstan-bot · 2026-07-07T07:53:05Z

This pull request has been marked as ready for review.

ondrejmirtes · 2026-07-07T11:04:22Z

Might be valuable to fix the escaped mutant. It means that either the code logic needs to change, or a test has to be added to fail when the code is changed this way.

zonuexe · 2026-07-07T11:24:54Z

@ondrejmirtes @staabm
On the Mutation Testing job: I built a local Infection setup with the same custom TrinaryLogicMutator and ran it (scoped to the affected files/suites, single-threaded) against the exact same mutation points. All of the mutants currently shown as escaped in CI come back as killed locally, the only mutant that actually escaped in my run was on an unrelated, pre-existing line. So this looks like something specific to the full CI run rather than these lines being under-tested.

ondrejmirtes · 2026-07-07T12:12:46Z

@zonuexe I don't think you need to set up Infection locally to verify this mutant. The question is: if you modify the file:

-			if ($parameter->isPureUnlessCallableIsImpureParameter()->no()) {
+			if (!$parameter->isPureUnlessCallableIsImpureParameter()->yes()) {

Do you get a failing test locally or not? If no tests fail the mutant is valid and then it's easy to fix the code/add the test.

Kills the TrinaryLogicMutator mutant on the parameter-flag check (->no() -> !->yes()) deterministically, without going through the analyser: a Maybe flag must be processed like Yes, so with the callback omitted the verdict is Yes, while the mutant skips the parameter and yields null.

Extend plain TestCase and pass a mocked Scope instead of booting the DI container and creating a real analyser Scope. The verdict method never consults the scope when no arguments are passed, so this keeps the test fully isolated (avoids interfering with other tests' shared state) while still killing the parameter-flag mutant.

Extract the verdict->yes()/->no() branching from createFromVariant() and NewHandler into SimpleImpurePoint::applyPureUnlessCallableIsImpureVerdict(), covered by a direct unit test. This removes the duplicated logic and lets the unit test deterministically kill the mutants on those branches instead of relying on coverage attribution from the rule tests.

Reverts 33f825a, f0cf3d4 and 4859c2f. Local Infection with the exact custom TrinaryLogicMutator kills every mutant on the changed lines (MSI 100%), so the remaining CI Mutation Testing failure is a coverage-attribution issue in the parallel run rather than a missing test - the added unit test and the verdict-to-certainty helper did not change that, so they are dropped to keep the PR focused on the reviewed changes.

zonuexe · 2026-07-07T14:12:23Z

I ran the exact custom TrinaryLogicMutator locally to check this properly.

Using the same mutator with --git-diff-lines over the changed files, and coverage generated from the Rules/Pure, Rules/Methods and Reflection/Callables suites, every mutant on the changed lines is killed by the test framework: 8 mutants generated, 8 killed, Covered Code MSI 100%, nothing escaped.

In CI the escaped mutant is a moving target: across the last three runs it was SimpleImpurePoint:151, then NewHandler:263/266, then NewHandler:262 - each killed by PureFunctionRuleTest locally (verified by hand-applying the ->yes() <-> !->no() mutation). So the tests do cover and kill these mutants; the remaining CI failure looks like coverage attribution in the parallel Infection run rather than a missing test.

I briefly tried a direct unit test plus factoring the verdict branching into one helper, but since that does not change the CI attribution I reverted it to keep the PR focused on the reviewed changes.

staabm · 2026-07-07T17:02:09Z

Thank you @zonuexe

zonuexe · 2026-07-07T17:05:20Z

I am always helped by the great work of the PHPStan team!

ondrejmirtes · 2026-07-07T17:06:27Z

Yeah, thank you!

And it's documented already. I love these times!

staabm · 2026-07-08T06:03:36Z

As a followup it would be great to look into phpstan 1st party extension packages and also often used packages in the php ecosystem, which could utilize the new phpdoc

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

Merged

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

staabm requested a review from VincentLanglet July 6, 2026 15:42

VincentLanglet approved these changes Jul 6, 2026

View reviewed changes

staabm reviewed Jul 7, 2026

View reviewed changes

zonuexe marked this pull request as draft July 7, 2026 05:28

zonuexe added 3 commits July 7, 2026 14:49

ondrejmirtes requested changes Jul 7, 2026

View reviewed changes

zonuexe added 2 commits July 7, 2026 16:15

zonuexe marked this pull request as ready for review July 7, 2026 07:52

zonuexe added 4 commits July 7, 2026 21:36

ondrejmirtes approved these changes Jul 7, 2026

View reviewed changes

ondrejmirtes merged commit 4dd8467 into phpstan:2.2.x Jul 7, 2026
668 of 672 checks passed

zonuexe deleted the feature/pure-unless-callable-is-impure branch July 7, 2026 16:42

zonuexe mentioned this pull request Jul 7, 2026

Implement @pure-unless-parameter-passed #6018

Open

3 tasks

zonuexe mentioned this pull request Jul 8, 2026

Add named argument tests for @pure-unless-callable-is-impure #6022

Merged

Uh oh!

Conversation

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

Uh oh!

How it works

Uh oh!

zonuexe Sep 25, 2024

Choose a reason for hiding this comment

Uh oh!

zonuexe Sep 25, 2024

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!

staabm Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

staabm Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

staabm Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ondrejmirtes left a comment

Choose a reason for hiding this comment

Uh oh!

ondrejmirtes Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

zonuexe commented Jul 7, 2026

Uh oh!

phpstan-bot commented Jul 7, 2026

Uh oh!

ondrejmirtes commented Jul 7, 2026

Uh oh!

zonuexe commented Jul 7, 2026

Uh oh!

ondrejmirtes commented Jul 7, 2026

Uh oh!

zonuexe commented Jul 7, 2026

Uh oh!

Uh oh!

staabm commented Jul 7, 2026

Uh oh!

zonuexe commented Jul 7, 2026

Uh oh!

ondrejmirtes commented Jul 7, 2026

Uh oh!

staabm commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

zonuexe commented Sep 25, 2024 •

edited by staabm

Loading

staabm Jul 6, 2026 •

edited

Loading

staabm Jul 7, 2026 •

edited

Loading