Repository navigation
Description
Feature request
With rememberPossiblyImpureFunctionValues: false, PHPStan stops remembering the return value of a method that only maybe has side effects. But what it narrowed about the properties of the object the method was called on is still remembered after the call. So when a method changes one of those properties, PHPStan reports comparisons of that property after the call as always true or always false, and they are wrong:
<?php declare(strict_types = 1);
class Tokenizer
{
/** @var 'ready'|'matched'|'complete' */
private string $state = 'ready';
public function nextToken(): bool
{
$this->state = 'ready';
if (!$this->parseNextTag()) {
return $this->state === 'complete';
}
return $this->state === 'matched';
}
private function parseNextTag(): bool
{
$this->state = rand(0, 1) === 1 ? 'matched' : 'complete';
return $this->state === 'matched';
}
}parameters:
level: 10
rememberPossiblyImpureFunctionValues: falsePHPStan 2.3.5 reports:
12: Strict comparison using === between 'ready' and 'complete' will always evaluate to false.
15: Strict comparison using === between 'ready' and 'matched' will always evaluate to false.
Playground, with "Remember possibly impure function values" unchecked: https://phpstan.org/r/50a65063-8832-4e69-96d8-3c8a4afa47a9
Today the fix is to mark parseNextTag() as @phpstan-impure. That works, but someone who has turned this option off has already said that they do not want PHPStan to assume that possibly impure calls change nothing. (This is what we're exploring for WordPress core.) Return values are covered, but properties are not, which makes the option only half of what its name suggests. In a state machine like the HTML API in WordPress core, that means tagging every method that advances the state, even though the option is meant to make that unnecessary.
Proposed behavior
When rememberPossiblyImpureFunctionValues is false, treat a call to a method whose hasSideEffects() is maybe the same as a call to one whose hasSideEffects() is yes, for the purpose of invalidating the object's properties. In practice:
- A method call (
$obj->foo(),$obj?->foo()) invalidates$obj. - A static call within the declaring class (
self::,static::,parent::) invalidates$this, or only the static properties when the method is static.
A method marked @phpstan-pure, or otherwise known to have no side effects, still leaves everything narrowed. With the option left on, which is the default, nothing changes.
A working prototype with tests is ready to open as a PR if the approach is acceptable.
Effect on a large codebase
On WordPress core at its configured level 5, with the option set to false:
- The change makes the
@phpstan-impuretag onWP_HTML_Tag_Processor::parse_next_tag()unnecessary. - It fixes two
identical.alwaysFalsefalse positives inWP_HTML_Processor::step(). In those,$last_errorwas set by a method called before an exception was thrown and caught. - It adds about five new errors. Each is a real possibility that the stale narrowing had hidden.
The alternative of tagging every method that writes object, class, or global state, enforced by a custom rule, came to about 750 @phpstan-impure tags in core: WordPress/wordpress-develop#16002
Open questions
- Should this reuse
rememberPossiblyImpureFunctionValues, perhaps behind bleeding edge, or should it get its own option? The option's name and documentation refer to return values, but turning it off already implies distrust of possibly impure calls. FuncCallHandlercould do the same for global state after a possibly impure function call. That is not part of the prototype.
This came out of a discussion in WordPress core, where it was pointed out that a type checker for an object-oriented language should not assume that method calls leave the object's state unchanged: WordPress/wordpress-develop#15917 (comment)
🤖 Issue initially drafted by Claude Opus 5.5 (medium effort)
Activity
westonruter commentedon Nov 14, 2026
🤖 Comment by Claude Opus 5.5 (medium effort)
Related issues: #13343 reports the same false positive and #11021 points to this option as the remedy for state changed by other calls, while #13550 shows why the change should stay behind the option.
Details
voidreturn type so that the method has side effects, which is not possible for a method that returns a value, such asparseNextTag()above.@phpstan-impureon a method whose result depends on shared state was called a workaround, andrememberPossiblyImpureFunctionValues: falsewas suggested as the way to avoid the problem. With the option off, return values are forgotten, but narrowed properties are still remembered, so the same kind of problem remains for properties.