Skip to content

Build/Test Tools: Stop PHPStan remembering possibly impure return values - #16003

Open
westonruter wants to merge 28 commits into
WordPress:trunkfrom
westonruter:remember-impure-values
Open

westonruter wants to merge 28 commits into
WordPress:trunkfrom
westonruter:remember-impure-values

Conversation

@westonruter

Copy link
Copy Markdown
Member

By default, PHPStan assumes that a function or method returns the same value every time it is called, unless it is marked @phpstan-impure. So when code checks a value, something changes it, and the code checks it again, PHPStan reports the second check as always true or always false. Silencing such a report usually means deleting a check that is actually needed. This came up in #15917 (comment), where the type checker was described as "instructing us to enter defects into code."

This PR sets rememberPossiblyImpureFunctionValues: false, so that PHPStan remembers only the return values of calls marked @phpstan-pure. A value read twice is no longer assumed to be the same.

Errors retired

The setting retires reports that relied on the assumption:

  • Five baseline entries, which empties the booleanAnd.leftAlwaysTrue baseline.
  • Three of the HTML Processor's ignored errors.
  • An inline ignore in Twenty Nineteen.

Errors fixed

The setting also exposes new errors, where a check on one call was relied on for a second call. Each is fixed in its own commit, usually by reading the value once into a variable:

  • Variables assigned under one call of a conditional and read under a second call of it, such as $update_data in wp-admin/menu.php and $children in wp_delete_post().
  • Repeated reads of WP_Theme::errors(), wp_get_referer(), WP_Error::get_error_data(), get_query_var( 'post_type' ), WP_REST_Response::get_data(), get_site_option( 'illegal_names' ), theme headers, the changeset post ID, a customizer setting, and an AI provider's logo path.
  • Two places in Site Health, and two templates each in Twenty Twenty and Twenty Twenty-One.
  • WP_Theme::parent(), checked and then called again in eight files. These errors appear only at level 7 and up.

Several of these values run through filters, so the code was relying on an assumption that was never guaranteed. Reading a value once also saves the repeated function calls and filter applications, a slight performance benefit.

@phpstan-impure tags removed

A later commit removes ten @phpstan-impure tags that existed only to stop PHPStan remembering return values, such as on current_user_can(), have_posts(), and WP_HTML_Tag_Processor::next_token(). A level 10 analysis reports the same errors with and without them.

The tag on WP_HTML_Tag_Processor::parse_next_tag() stays. Whatever this setting is, PHPStan keeps what it has narrowed about an object's properties after a call to a method that is not marked impure. A change to PHPStan to make it forget them too has been proposed in phpstan/phpstan#15734.

The last three commits fix the errors that a prototype of that change reports here, without adding any annotations. Once it is released:

  • The tag on parse_next_tag() can be removed.
  • The WP_Upgrader_Skin::$api baseline count for Theme_Upgrader must be raised from 2 to 3.
  • The $last_error ignore entry for the HTML Processor can be removed.

No purity annotations needed

No @phpstan-pure tags are added either, since core does not depend on them. This bears on related PRs:

  • Docs: Add PHPStan purity annotations #14095 adds @phpstan-pure to 75 functions. With this setting, that tag is what lets PHPStan remember a function's return value, so those annotations would mean more than they do now. They are not needed for core's own analysis, though, so they could go to wordpress-stubs instead. Either way, the tag would still make PHPStan check that those functions stay free of side effects.
  • That PR also leaves open which functions to mark @phpstan-impure. This PR answers that for core: none, once the PHPStan change is released. Plugins analyzed with PHPStan's default setting could still use such annotations, which could also come from wordpress-stubs.
  • Build/Test Tools: Add and enable a PHPStan rule requiring @phpstan-impure on methods that change state #16002 explores the alternative: a rule requiring @phpstan-impure on every method that changes state.

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: Changing the PHPStan setting, fixing the errors it exposed, and writing the commit messages, 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 27 commits November 13, 2026 23:33
…ues.

By default, PHPStan assumes a call returns the same value every time unless
the function is marked `@phpstan-impure`, so a repeated check is reported as
always true or always false even when global state has changed in between.
Silencing such a report tends to mean deleting a check that is needed.

Set `rememberPossiblyImpureFunctionValues: false`, so that only calls marked
`@phpstan-pure` are remembered. Errors then lean conservative: a value read
twice is not assumed to be the same.

This retires reports that relied on the assumption:

* Five baseline entries for `if.alwaysTrue`, `booleanNot.alwaysTrue`, and
  `booleanAnd.leftAlwaysTrue`, emptying the last of those baselines.
* Three of the HTML Processor's ignored errors.
* The inline ignore in Twenty Nineteen's `header.php`, which was needed only
  because `twentynineteen_can_show_post_thumbnail()` was assumed unchanged by
  `the_post()`.

It also exposes nine `variable.undefined` errors, where a variable is assigned
under one call of a conditional and read under a second call of it. These are
baselined here and fixed in a follow-up.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
In these places a variable is assigned under one call of a conditional and
read under a second call of the same conditional. That holds only if the
conditional returns the same value both times, which PHPStan no longer
assumes now that it does not remember possibly impure return values.

Either initialize the variable before the first check, where the second
check never reads it otherwise, or read the conditional once into a local
variable:

* `$show_network_active` in `WP_Plugins_List_Table::prepare_items()`.
* `$authors_dropdown` in `WP_Posts_List_Table::inline_edit()`.
* `$update_data` in `wp-admin/menu.php`, using the `! isset()` guard the
  file already uses for the Themes and Plugins submenus.
* `$children` in `wp_delete_post()`.
* `is_subdomain_install()` in `show_blog_form()`.
* `is_post_type_archive()` in `wp_title()`.
* `has_post_thumbnail()` in Twenty Eleven's showcase template.

This empties the baseline entries for these errors.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
A common pattern checks `$theme->errors()` and then calls a method on a
second `$theme->errors()`, such as `get_error_message()`. Now that PHPStan
no longer remembers possibly impure return values, it does not assume the
second call returns the `WP_Error` that the first one did, and reports
calling a method on `WP_Error|false`.

`errors()` cannot be marked `@phpstan-pure`, since it calls `is_wp_error()`,
which fires the `is_wp_error_instance` action. So read it once into a
variable instead, and use that for both the check and the call.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
Callers commonly check `$theme->parent()` and then call a method on a second
`$theme->parent()`. Now that PHPStan no longer remembers possibly impure
return values, it does not assume the second call returns the `WP_Theme`
that the first one did, and reports calling a method on `WP_Theme|false`.

Unlike `WP_Theme::errors()`, the method only reads a property, so it can be
marked `@phpstan-pure`. This fixes every such caller at once, and it lets
plugins analyzed against these docblocks benefit too.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
These callers check `wp_get_referer()` and then pass a second call of it to
a function expecting a string. Now that PHPStan no longer remembers possibly
impure return values, it does not assume the second call is truthy too, and
reports passing `string|false`. Since the result runs through the
`allowed_redirect_hosts` filter, the assumption is not guaranteed anyway.

Read it once into a variable instead. Each is structured so that
`wp_get_referer()` is called under the same conditions as before:

* In `wp-admin/comment.php`, the first operand of the condition already
  called it unconditionally. The `wp_get_original_referer()` check that
  follows had the same pattern, so it is read once too, in an `else` that
  keeps it from being called when the first branch matches.
* In `wp-admin/edit-comments.php`, it moves into the final `else` of the
  chain, in place of the `elseif`.
* In `auth_redirect()`, it is still called only for `options.php` requests,
  falling back to the current URL as before.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`WP_Site_Health::get_test_scheduled_events()` called `has_missed_cron()` to
check for a `WP_Error`, again to read the error message, and again to check
for a missed event. The method is not pure: it compares against `time()` and
records `$last_missed_cron`. So, now that PHPStan no longer remembers possibly
impure return values, it reports calling `get_error_message()` on
`bool|WP_Error`.

Call it once and reuse the result for all three checks.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
…t()`.

`WP_Site_Health::enqueue_scripts()` and `wp_cron_scheduled_check()` checked
`is_callable( array( $this, $test_function ) )` and then passed a second,
separately built `array( $this, $test_function )` to `perform_test()`, which
expects a `callable`. With PHPStan no longer remembering possibly impure
return values, the narrowing from the check is not carried over to the
second array, and it is reported as `array{$this, non-falsy-string}`.

Build the callback once, check it, and pass that same value.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
The attachment template and `twenty_twenty_one_post_thumbnail()` checked
`wp_get_attachment_caption()` and then printed a second call of it. Now
that PHPStan no longer remembers possibly impure return values, it does not
assume the second call is truthy too, and reports passing `string|false` to
`wp_kses_post()`. The caption runs through the `wp_get_attachment_caption`
filter, so the assumption is not guaranteed anyway.

Read the caption once into a variable instead, which also saves a lookup.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
The attachment template checked `wp_get_post_parent_id()` and then called it
twice more for the parent's permalink and title. Now that PHPStan no longer
remembers possibly impure return values, it does not assume those calls
return the same nonzero ID, and reports passing `int|false` to
`get_the_permalink()` and `get_the_title()`.

Read the ID once into a variable and reuse it. Since the template now reads
the global `$post` once instead of three times, the baselined count of
`$post` possibly being undefined there drops by two.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`validate_theme_requirements()` checked `$theme->get( 'RequiresWP' )` and
`$theme->get( 'RequiresPHP' )` for emptiness and then called each again for
the value. Now that PHPStan no longer remembers possibly impure return
values, it does not assume the second call is non-empty too, and reports
passing `string|false` to `is_wp_version_compatible()` and
`is_php_version_compatible()`.

Read each header once into a variable instead.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`TwentyTwenty_Walker_Comment::html5_comment()` checked
`get_edit_comment_link()` and then passed a second call of it to
`esc_url()`. Now that PHPStan no longer remembers possibly impure return
values, it does not assume the second call is non-null too, and reports
passing `string|null`. The link runs through the `get_edit_comment_link`
filter, so the assumption is not guaranteed anyway.

Read the link once into a variable instead.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`WP_Customize_Manager::import_theme_starter_content()` and
`customize_pane_settings()` checked `$this->changeset_post_id()` and then
passed a second call of it to a function expecting an ID. The method looks
up and caches the ID on first use, so it is not pure. Now that PHPStan no
longer remembers possibly impure return values, it does not assume the
second call is non-null too, and reports passing `int|null`.

In `import_theme_starter_content()`, read the ID once into a variable. In
`customize_pane_settings()`, reuse the `$changeset_post_id` variable it
already reads at the start.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`WP_Customize_Nav_Menus::load_available_items_query()` checked
`$this->manager->get_setting( 'nav_menus_created_posts' )` and then called
`value()` on a second lookup of it. Now that PHPStan no longer remembers
possibly impure return values, it does not assume the second lookup finds
the setting too, and reports calling `value()` on
`WP_Customize_Setting|null`.

Look the setting up once into a variable instead. As before, the lookup only
happens for the first page.

`get_setting()` is not marked `@phpstan-pure` instead: a pure method's
result would be remembered across calls that change the settings by other
means than this instance, such as a hook calling `remove_setting()` on the
global `$wp_customize`.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
The AI provider registration checked `$provider_metadata->getLogoPath()` and
then passed a second call of it to `_wp_connectors_resolve_ai_provider_logo_url()`.
Now that PHPStan no longer remembers possibly impure return values, it does
not assume the second call is non-null too, and reports passing
`string|null`.

The method belongs to the bundled PHP AI Client, which is not modified here,
so read the path once into a variable instead of marking it pure.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`wp_ajax_widgets_order()` iterated `wp_unslash( $_POST['sidebars'] )`
directly. With PHPStan no longer remembering possibly impure return values,
the keys of that loop are typed `mixed` after the preceding `unset()` of
other `$_POST` keys, and using one as a key of `$sidebars` is reported as a
possibly invalid array key type.

Assign the unslashed array to a variable first. PHPStan then types the keys
as `int|string` whether or not it remembers return values.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
The upgrader skins, `show_message()`, and `WP_Customize_Manager::save()`
checked the type of `get_error_data()` and then used a second call of it. Now that PHPStan no longer remembers possibly impure
return values, it does not carry the check over to the second call, and
reports passing `mixed` where a string or an array is expected.

Read the data once into a variable instead, and use that for both the check
and the value.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`redirect_guess_404_permalink()` called `get_query_var( 'post_type' )` five
times: to check it is set, to check whether it is an array, and to use it.
Now that PHPStan no longer remembers possibly impure return values, it does
not carry the `is_array()` check over to the next call, and reports passing
`mixed` to `array_intersect()`.

Read the query var once into a variable instead.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`WP_REST_Response::as_error()` checked `is_array( $this->get_data() )` and
then assigned a second call of `get_data()` to `$data`. Now that PHPStan no
longer remembers possibly impure return values, it does not carry the check
over to the assigned value, and reports accessing offsets on `mixed`.

Assign the data first and check that variable instead.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`wp-signup.php` checked `is_array( get_site_option( 'illegal_names' ) )` and
then searched a second call of it with `in_array()`. Now that PHPStan no
longer remembers possibly impure return values, it does not carry the check
over to the second call, and reports passing `mixed` as the haystack. The
option runs through filters, so the assumption is not guaranteed anyway.

Read the option once into a variable instead.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
…data.

`wp-admin/menu.php` assigns `$update_data` only when the site is not a
multisite or the user can update core, and its Updates, Themes, and Plugins
submenus read it under separate `! is_multisite()` checks. Now that PHPStan
no longer remembers possibly impure return values, it cannot tell that the
first assignment ran. Since the file runs in global scope, it then types a
set `$update_data` as `mixed`, and reports every offset read from it.

Read `is_multisite()` once into a variable and use it for all four checks.
PHPStan can then connect them, so it knows the update data is set wherever
it is read. This also removes the fallback that an earlier commit added to
the Updates submenu, which could never run, since on a single site the data
has always been fetched by then. The variable is unset with `$update_data`
at the end of the file.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
`WP_Automatic_Updater::after_core_update()` checked
`is_wp_error( $result->get_error_data()->rollback )` and then assigned a
second `$result->get_error_data()->rollback` to `$rollback_result`. Now that
PHPStan no longer remembers possibly impure return values, it does not carry
the check over to the assigned value, and reports calling `get_error_code()`
and `get_error_data()` on `mixed`.

Read the error data once, next to the error code, and use it for the
rollback check and both records of the failure.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
…ing impure values.

With `rememberPossiblyImpureFunctionValues` set to false, PHPStan no longer remembers the return value of a call that is not marked `@phpstan-pure`. The tags on `chmod()`, `current_user_can()`, `is_html()`, `have_posts()`, `have_comments()`, `next_token()`, `next_tag()`, and `has_previous_version()` only existed to stop that remembering, so they are removed. A level 10 analysis reports the same errors with and without them. Plugins that want them can get them from the wordpress-stubs package.

The tag on `WP_HTML_Tag_Processor::parse_next_tag()` stays. PHPStan clears what it has narrowed about an object's properties after a method call only when the method is known to be impure, whatever this setting is. Without the tag, `$this->parser_state` stays narrowed to `STATE_READY` after the call, so the checks that follow look always true or false and `skip_rawtext()` and `skip_script_data()` look unused.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
…ure.

`WP_Block_Processor::next_delimiter()` sets `$this->state` to `READY`, scans for a delimiter in a loop that assigns `$comment_opening_at`, and reads that variable after the loop when the state is `MATCHED`, which only the loop sets. The loop calls `find_html_comment_end()`. A version of PHPStan that forgets an object's narrowed properties after a possibly impure method call, as proposed in phpstan/phpstan#15734, then no longer knows the state after the loop. It reports `$comment_opening_at` as possibly undefined three times.

The method only reads `$this->source_text`, so mark it `@phpstan-pure`. PHPStan then knows the call leaves the state alone.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3JtcvQrtFGa2fwY9Ay
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
… list table.

`WP_MS_Themes_List_Table::prepare_items()` assigns `$auto_updates` under `if ( $this->show_autoupdates )` and reads it in the loop under a second check of the same property, with method calls in between. A version of PHPStan that forgets an object's narrowed properties after a possibly impure method call, as proposed in phpstan/phpstan#15734, does not assume the property is unchanged by those calls. It reports `$auto_updates` as possibly undefined.

Initialize it to an empty array before the first check, as the earlier fixes for this pattern do. The second check never reads it otherwise.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3JtcvQrtFGa2fwY9Ay
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
…marking a method pure.

The previous commit marked `WP_Block_Processor::find_html_comment_end()` as `@phpstan-pure` so that PHPStan would keep knowing `$this->state` across its calls in `next_delimiter()`. That trades one annotation for another, when the goal is to need neither.

Instead, set a local `$matched` flag alongside `$this->state = self::MATCHED` before each `break`, and check that flag after the loop. A method call cannot change a local variable, so PHPStan knows `$comment_opening_at` is defined whenever `$matched` is true, with or without the forgetting proposed in phpstan/phpstan#15734. Remove the `@phpstan-pure` tag.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3JtcvQrtFGa2fwY9Ay
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
…then used.

Callers commonly check `$theme->parent()` and then call a method on, or read a property of, a second `$theme->parent()`. Now that PHPStan no longer remembers possibly impure return values, it does not assume the second call returns the `WP_Theme` that the first one did, and at level 7 and up it reports calling a method on `WP_Theme|false`.

Read the parent theme once into a variable in `Theme_Upgrader::check_parent_theme_filter()`, `WP_MS_Themes_List_Table::column_description()`, `WP_Site_Health::get_test_theme_version()`, `wp_prepare_themes_for_js()`, the theme file editor, `_register_theme_block_patterns()`, `WP_Theme_JSON_Resolver::get_theme_data()`, and `WP_Theme`'s own `__get()`, `offsetGet()`, `get_template_directory()`, and `get_template_directory_uri()`. In `Theme_Upgrader`, this also fixes three existing errors, since `theme_info()` can return false and its `parent()` was called four times.

This lets the next commit remove the `@phpstan-pure` tag added to `WP_Theme::parent()`, leaving any purity annotations to the stubs used by plugins.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3JtcvQrtFGa2fwY9Ay
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
The previous commit reads the parent theme once wherever it is checked and then used, so core no longer relies on PHPStan remembering the return value of `WP_Theme::parent()`. The tag was the only purity annotation this branch added for that purpose. Annotations for consumers of these APIs, such as plugins analyzed against them, can be supplied by stubs instead.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3JtcvQrtFGa2fwY9Ay
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
@westonruter
westonruter marked this pull request as ready for review November 15, 2026 02:54
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter, dmsnell.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@westonruter
westonruter requested a review from dmsnell November 15, 2026 02:55
@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.

@dmsnell dmsnell left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, it looks like a lot of potential races are covered here, and maybe some latent performance silliness.

Some of the code is verbose, but it looks like it’s a step up in ensuring that we don’t make assumptions about the functions.

I think it would be interesting to review all of the functions now trapped in a variable and see if any of them are actually impure in a way that matters. That is, for example, if find_changeset_post_id() could return a different result across multiple calls (which seems plausible, but only in going from false to an id), then capturing its value in a variable creates a new race. This is, I think, the same mistake PHPStan makes in assuming that these are pure. Of course, while such a situation would leave a runtime bug, it would be removing the type error.

wp_get_post_parent_id() seems like a more likely opportunity for a data race in practice, but I think the new behavior stands as a better experience: it’s better to render a page coherently with out-of-date information than to render part of a page using one post and the rest of the page with another (not claiming this does that, because we still have sequential database queries, but it moves towards that direction).

No @phpstan-pure tags are added either

It’s unfortunate that calls to return max( $w, $h ) ... require annotation, but that seems mildly preferable to @phpstan-impure given that the safe assumption is impurity until demonstrated pure.

Maybe PHPStan could improve its inference in time. I guess if no actual constraint enforced int types then a class could be state fully-passed into these functions.


Curious how you feel about these changes. They seem like the kind of warnings our type system should be making: that is, instead of telling developers you should take out these guards because nothing will ever be wrong here it’s saying you know this could be something else, right?

Comment thread src/wp-admin/menu.php

$count = '';
if ( ! is_multisite() && current_user_can( 'update_plugins' ) ) {
if ( ! $is_multisite && current_user_can( 'update_plugins' ) ) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a good example of a function that should be inferable as pure, though I suppose it’s possible to call it in one case without constants being defined, then through inclusion of another PHP file, the constants are newly defined.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right. It's very unlikely for the value to ever not change during WP's lifecycle, but a constant could be defined at any time. So there are global side effects which influence the function's return value.

Comment thread src/wp-admin/menu.php
}

unset( $update_data );
unset( $update_data, $is_multisite );

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does the boolean cause memory issues? or is it because it’s a global variable?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to clean up the global scope, yeah.


// The end of the document was reached without a match.
if ( self::MATCHED !== $this->state ) {
if ( ! $matched ) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what’s the problem here that requires the auxiliary variable?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's preempting the change proposed in phpstan/phpstan#15734 where rememberPossiblyImpureFunctionValues would apply to class properties in addition to return values. So it allows us keep the @phpstan-pure removed and remain compatible with that proposed change to PHPStan: phpstan/phpstan-src#7073.

We could revert these changes, but if that PR is merged in a new release, then we'd need to add the local variable.

Reference commit 72e0c73.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still don’t get it. it looks like we’re taking a single read of $this->state against a type-equivalent equality check, and replacing it with a duplicate variable.

but we never read $this->state inside the if body. what is there to forgot or not forget here?

$redirect = wp_get_referer();
} else {
}
if ( ! $redirect ) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a counter-example to the pattern of extracting into a variable. it read awkwardly and the original short-circuiting if was clearer.

case 'parent_theme':
return $this->parent() ? $this->parent()->get( 'Name' ) : '';
$parent = $this->parent();
return $parent ? $parent->get( 'Name' ) : '';

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PHP 8.0 would help here with $this->parent()?->get( 'Name' ) ?? ''

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it would because, unfortunately, because WP_Theme::parent() returns false when it's not a child theme, not null.

Trunk reverted the Secrets API in 53ea800, deleting `tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php`, from which this branch had removed a `@phpstan-impure` tag. The deletion is kept.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3JtcvQrtFGa2fwY9Ay
Claude-Code-Session-Id: dfb24569-a61a-4404-8588-60a387d2cccb
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.

2 participants