Repository navigation
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
Draft
westonruter wants to merge 3 commits into
westonruter wants to merge 3 commits into
Conversation
…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
@phpstan-impure@phpstan-impure on methods that change state
Test using WordPress PlaygroundThe 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
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
This was referenced Nov 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-puremeans none, while@phpstan-impure, avoidreturn type, or returning$thismeans 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, callsparse_next_tag(), and then checks$this->parser_stateagain. TherememberPossiblyImpureFunctionValues: falsesetting 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-pureand@phpstan-all-methods-impuretags, andvoidor$thisreturns. An optional transitive mode, off by default, also reports methods that change state only by calling another impure method of the class.The commits:
@phpstan-impureto all 747 methods it reports, across 215 files. It also updates the PHPStan results that the tags change.tests/phpstan/base.neon.What the tags change in PHPStan's results:
WP_Upgrader_Skin::$apiproperty inTheme_Upgrader::install()is reported a third time, so its baseline count goes from 2 to 3. One of the two$last_errorchecks inWP_HTML_Processor::step()is no longer reported as always false, so that ignore entry's count drops to 1. The other check follows a directbookmark_token()call, and a catch block sees the scope from before the call's side effects apply, so no tag can fix it.array|nullwhere PHPStan had narrowed toarray.Findings across
src/:@phpstan-impuretags.get_instance()singletons,WP_Rewrite::get_*_permastruct(), andWP_List_Table::get_column_info(). Tagging them would be accurate but gain nothing.parse_next_attribute(), theskip_*()methods, thestep_*()methods, andseek(), all following the same state-machine pattern asparse_next_tag().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-impureoverrides, 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. WhenrememberPossiblyImpureFunctionValuesis 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-impuretag onWP_HTML_Tag_Processor::parse_next_tag()unnecessary, along with both of the$last_errorchecks 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.