Skip to content

Build/Test Tools: Add and enable a PHPStan rule requiring @phpstan-impure on methods that change state - #16002

Draft
westonruter wants to merge 3 commits into
WordPress:trunkfrom
westonruter:impure-rule
Draft

westonruter wants to merge 3 commits into
WordPress:trunkfrom
westonruter:impure-rule

Conversation

@westonruter

@westonruter westonruter commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Note

This is not seriously intended for proposing for commit. It is only for posterity.

This is an exploration, kept for reference and not intended for commit. It adds a PHPStan rule that reports methods which change state but are not marked @phpstan-impure, enables it, and adds every tag it demands, so the diff shows what enforcing it would cost.

PHPStan never looks inside a method's body when it analyzes a call to it. It judges side effects from the signature alone: @phpstan-pure means none, while @phpstan-impure, a void return type, or returning $this means some. Any other method only "maybe" has side effects. After a call to such a method, PHPStan keeps what it had narrowed about the object's properties. So when the method changes those properties, the caller gets comparisons reported as always true or always false, and they are wrong. WP_HTML_Tag_Processor::next_token() is an example: it sets $this->parser_state, calls parse_next_tag(), and then checks $this->parser_state again. The rememberPossiblyImpureFunctionValues: false setting does not change this, because it covers only return values.

The rule reports non-void methods with no purity tag that write to properties of $this, to static properties, or to globals. It skips what PHPStan already handles: tags inherited from a parent, the class-level @phpstan-all-methods-pure and @phpstan-all-methods-impure tags, and void or $this returns. An optional transitive mode, off by default, also reports methods that change state only by calling another impure method of the class.

The commits:

  1. a15a583 adds the rule.
  2. e1814b3 adds @phpstan-impure to all 747 methods it reports, across 215 files. It also updates the PHPStan results that the tags change.
  3. e1c6c06 registers the rule in tests/phpstan/base.neon.

What the tags change in PHPStan's results:

  • At the configured level 5, only two results change. An access to the undefined WP_Upgrader_Skin::$api property in Theme_Upgrader::install() is reported a third time, so its baseline count goes from 2 to 3. One of the two $last_error checks in WP_HTML_Processor::step() is no longer reported as always false, so that ignore entry's count drops to 1. The other check follows a direct bookmark_token() call, and a catch block sees the scope from before the call's side effects apply, so no tag can fix it.
  • At level 10, errors go from 26,761 to 26,776: 30 new and 14 gone. Most of the new ones are properties widening back to their declared types after a call that is now impure, such as array|null where PHPStan had narrowed to array.

Findings across src/:

  • About 750 methods are reported: roughly 600 public, 85 private, and 65 protected. Before this PR, core had 16 @phpstan-impure tags.
  • Every hit is technically accurate, but few would ever cause a false positive. That happens only when a caller narrows a property, calls the method, and then reads the property again.
  • At least a fifth are memoizers or lazy initializers, such as get_instance() singletons, WP_Rewrite::get_*_permastruct(), and WP_List_Table::get_column_info(). Tagging them would be accurate but gain nothing.
  • The HTML API accounts for 42 hits. These include parse_next_attribute(), the skip_*() methods, the step_*() methods, and seek(), all following the same state-machine pattern as parse_next_tag().
  • The transitive mode adds only 18 more.

The public methods in this list may be more useful to the wordpress-stubs package than to core itself. Plugins and themes analyzed against those stubs usually keep PHPStan's default rememberPossiblyImpureFunctionValues: true, so a public core method that changes state can mislead them in two ways. Repeated calls look like they return the same value, and a public property narrowed before a call looks unchanged after it. Running the audit against each core release would give the stubs a mechanical source of @phpstan-impure overrides, and core would not need to carry those tags.

The conclusion is that enforcing the rule costs little in analysis results but a great deal in docblock noise, so it works better as an audit than as a requirement. Reporting only private and protected methods, and exempting writes guarded by isset() on the same property, would remove most of the noise. A better fix is in PHPStan itself. When rememberPossiblyImpureFunctionValues is false, it could forget narrowed properties after any call that is not known to be pure. A local prototype of that change makes the @phpstan-impure tag on WP_HTML_Tag_Processor::parse_next_tag() unnecessary, along with both of the $last_error checks covered by the ignore entry for the HTML Processor. It adds about five errors at level 5, each a real possibility, not a false positive.

This came out of the discussion in #15917 (comment) and #15917 (comment).

Trac ticket: https://core.trac.wordpress.org/ticket/65817

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5 (medium effort)
Used for: Investigating PHPStan's purity handling, writing the rule, and measuring its results across core, under the direction of the PR author.


This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

westonruter and others added 3 commits November 14, 2026 11:54
…state without `@phpstan-impure`.

PHPStan decides whether a call has side effects from the method's signature alone. A method that returns a value and has no purity tag only "maybe" has side effects, so after a call to it PHPStan keeps whatever it had narrowed about the object's properties. When such a method changes those properties, callers get always-true or always-false comparisons that are wrong.

`MissingImpureTagRule` reports these methods: non-void ones with no purity tag that write to properties of `$this`, to static properties, or to globals. It can also report methods that change state only through another impure method of the class. It is not enabled by default, because across `src/` it finds about 750 methods, most of which never mislead a caller. `tests/phpstan/missing-impure-tag-rule.neon` enables it for an audit.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
This adds `@phpstan-impure` to the 747 methods that `MissingImpureTagRule` reports: non-void methods with no purity tag that write to properties of `$this`, to static properties, or to globals. The tags tell PHPStan to forget what it has narrowed about an object after calling one of these methods.

At the configured level, this changes two results:

* An access to the undefined `WP_Upgrader_Skin::$api` property in `Theme_Upgrader::install()` is now reported a third time, because `$this->skin` is no longer known to be the skin it was narrowed to.
* One of the two `$last_error` checks in `WP_HTML_Processor::step()` is no longer reported as always false, now that the `step_*()` methods are impure. The one after the direct `bookmark_token()` call remains, since a catch block sees the scope from before the call's side effects.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
Now that every method it reports is marked `@phpstan-impure`, the rule is registered in the base configuration, so that new methods that change state are held to the same requirement. The opt-in configuration file is no longer needed.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
@westonruter westonruter changed the title Build/Test Tools: Add an opt-in PHPStan rule for methods that change state without @phpstan-impure Build/Test Tools: Add and enable a PHPStan rule requiring @phpstan-impure on methods that change state Nov 14, 2026
@github-actions

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant