Skip to content

Forget narrowed properties after a possibly impure method call when rememberPossiblyImpureFunctionValues is false #15734

Open
phpstan/phpstan-src
#7073

Description

@westonruter

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: false

PHPStan 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-impure tag on WP_HTML_Tag_Processor::parse_next_tag() unnecessary.
  • It fixes two identical.alwaysFalse false positives in WP_HTML_Processor::step(). In those, $last_error was 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.
  • FuncCallHandler could 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

  1. westonruter commented on Nov 14, 2026

    @westonruter
    ContributorAuthor

    🤖 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions