Plugins: Prevent hook callback IDs from being cast to integer array keys

[westonruter]

In r62408, spl_object_hash() was replaced with spl_object_id() in two places. In both, the resulting array key is no longer a string, and in both the array holding it is a public property that plugins introspect.

Committed in r63334. Core-65919 is reopened for 7.1.1 merge consideration.

WP_Hook::$callbacks

The unique ID that _wp_filter_build_unique_id() builds for a callback that is a bare object (e.g. a closure or an instance with __invoke()) became the return value of spl_object_id() cast to a string, for example "5292".

PHP casts an array key from string to int whenever the string is the canonical decimal representation of an integer, so that (string) cast is undone one layer down, at the point where the ID becomes a key in WP_Hook::add_filter():

$this->callbacks[ $priority ][ $idx ] = array( ... );

The keys therefore became integers for bare-object callbacks, where every release through 7.0.x stored the 32 character hex string returned by spl_object_hash(). Any consumer running under strict_types, or passing a key to a parameter declared string, now fatals:

foreach ( $wp_filter['init']->callbacks[10] as $id => $cb ) {
	$prefix = substr( $id, 0, 3 );
	// TypeError: substr(): Argument #1 ($string) must be of type string, int given
}

Prefix the ID with a non-numeric literal so PHP leaves it a string:

return 'spl_object_id:' . spl_object_id( $callback );

Only bare-object callbacks are affected. [ $obj, 'method' ] already yields "5292method", and function names and Class::method are returned unchanged, so no other key format changes.

WP_Widget_Factory::$widgets

The same changeset made the equivalent replacement in WP_Widget_Factory::register() and unregister(), there without any cast at all:

-	$this->widgets[ spl_object_hash( $widget ) ] = $widget;
+	$this->widgets[ spl_object_id( $widget ) ] = $widget;

So the key for a widget registered as an instance is a genuine int, and WP_Widget_Factory::$widgets is public as well.

This one also breaks a contract inside core. get_widget_key() documents that it returns a string, and returns the array key straight out of its loop. Both render_block_core_legacy_widget() and WP_REST_Widget_Types_Controller pass what it returns to the_widget(), whose first parameter is documented string, and which forwards it to the the_widget action, documented the same way. Nothing fatals inside core, because the lookups agree on the integer — but any the_widget listener declaring function ( string $widget ) under strict_types does.

The same prefix applies, held in one place so the two call sites cannot drift:

private const INSTANCE_KEY_PREFIX = 'spl_object_id:';

Guarding against a recurrence

The tests added in r62408 asserted the return type of _wp_filter_build_unique_id(), which was correctly string. They did not assert the type of the resulting array key, which is where the coercion happens, so the regression passed through them. WP_Widget_Factory had no key assertions at all.

The tests now assert what actually matters, by round-tripping the value through an array key, the runtime equivalent of PHPStan's non-decimal-int-string:

private function assertIsNonDecimalIntString( $value ): void {
	$this->assertIsString( $value, 'The unique ID is not a string.' );

	$array = array( $value => true );

	$this->assertIsString(
		array_key_first( $array ),
		sprintf( 'The unique ID "%s" was cast to an integer when used as an array key.', $value )
	);
}

Coverage for an invokable object callback is added, which had none, as are two tests for the widget factory keys.

Static analysis is tightened in three places:

• _wp_filter_build_unique_id() declares @phpstan-return non-decimal-int-string|null. PHPStan already infers (string) spl_object_id( $x ) as decimal-int-string, so reintroducing the bare cast is reported as a return.type error from rule level 3 upwards, well inside the level 5 this project analyses at.
• The WP_Hook::$callbacks key type is narrowed from string to non-decimal-int-string, along with the Iterator and ArrayAccess type parameters and the offsetGet(), offsetSet(), current(), and next() signatures describing the same array. Analysing the tree at level 8 produces an identical error set before and after, so it costs nothing, and it catches the separate case of the unique ID type widening back to a plain string.
• WP_Widget_Factory::$widgets declares @phpstan-var array<non-decimal-int-string, WP_Widget> beneath a plain @var array<string, WP_Widget>, the way WP_Hook::$callbacks already carries the same type. A plain string key was used at first, on the grounds that PHPStan evaluates both of that class's writes inline — typing a bare spl_object_id() as int and a cast one as decimal-int-string, and modelling the latter as producing an array<int, …> — so array<string, …> already rejects both regression shapes without the extra report narrowing brings. That weighed the wrong thing: neither key type produces a single report below rule level 7, so at the level this project analyses at the choice is invisible, and two properties disagreeing about the type of a key built the same way costs more than the one report narrowing adds. The value type is a separate gain, retiring several reports of accessing a property or calling a method on mixed; analysing that file at level 10 goes from six errors to three.

Two limitations are worth flagging for anyone raising the rule level later, both invisible at level 5:

• PHPStan has no type for a string carrying a known literal prefix, so it infers only non-falsy-string for either fixed expression and cannot verify it. That produces one report in each file — on the return in _wp_filter_build_unique_id() and on the instance write in WP_Widget_Factory::register() — from level 7 upwards.
• The branch of WP_Widget_Factory::register() that registers by class name assigns an object where a WP_Widget is declared, since neither the type system nor WP_Widget expresses that a subclass named for registration must have a constructor callable with no arguments. Also level 7 upwards.

Testing instructions

Before this patch, the two new key assertions fail in each place:

✘ Closure returns string
  │ The unique ID "92588" was cast to an integer when used as an array key.
✘ Invokable object returns string
  │ The unique ID "431" was cast to an integer when used as an array key.

✘ Register widget instance is keyed by string
  │ Failed asserting that 92581 is of type "string".
✘ Get widget key for instance returns string
  │ Failed asserting that 432 is of type "string".

After it:

• --filter Tests_Hooks_BuildUniqueId — 9 tests, 15 assertions
• --filter Tests_Widgets — 130 tests, 778 assertions
• --group hooks — 168 tests
• PHPStan reports no errors across the analyzed tree

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

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Investigating whether PHPStan could be configured to catch this class of bug, drafting the test changes and the fixes, and running the PHPStan and PHPUnit verification. I reviewed and take responsibility for all of it.

---

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.

[github-actions]

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.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

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

Props westonruter, sergeybiryukov.

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

[github-actions]

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 63334
GitHub commit: e63f564

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.