#64896 Fix remaining PHPStan level 10 errors in `WP_Hook` by westonruter · Pull Request #12443 · WordPress/wordpress-develop

westonruter · 2026-07-07T21:14:21Z

This is stacked on #12441 and includes all of its commits. The only new commit here is b0d8b59, which resolves the remaining PHPStan level 10 errors in WP_Hook on top of the type tightening done in that PR. @johnbillion: feel free to merge this into your branch if you want to fold it in; otherwise I'll rebase onto trunk once your PR lands.

The new commit:

Adds @return void to the methods lacking return values.
Documents the callback $args arrays as list<mixed> and narrows the $callback params of remove_filter()/has_filter() to callable, matching add_filter().
Passes 0 instead of false to _wp_filter_build_unique_id() in has_filter(), matching its int $priority param. (The value is unused for the key, so this is behavior-neutral.)
Restructures the apply_filters() loop to assign the current priority to a local variable before storing it in $current_priority, bailing from the loop in the (impossible) case that current() returns false. This keeps $current_priority honestly typed as array<int, int>; previously, PHPStan saw int|false being stored.

With this, composer phpstan src/wp-includes/class-wp-hook.php reports no errors at level 10.

Local phpstan.neon overrides

includes:
	- phpstan.neon.dist
	- vendor/phpstan/phpstan/conf/bleedingEdge.neon

parameters:
	# https://phpstan.org/user-guide/rule-levels
	level: 10

	editorUrl: 'phpstorm://open?file=%%file%%&line=%%line%%'

	# Narrow scanDirectories to source subdirs only. Pointing at plugin roots causes
	# PHPStan to traverse vendor/ and node_modules/ (~9k files), which dominates
	# startup time — excludePaths does not prune the traversal.
	scanDirectories:
		- tests/phpunit

	ignoreErrors:
		- '#^Cannot cast mixed to int\.$#'
		# FTP\Connection is PHP 8.1+; the @var is correct for WP's 7.4+ range, but
		# bleedingEdge's version-aware check flags it against the PHP 7.4 floor.
		-
			identifier: class.notFound
			path: src/wp-admin/includes/class-wp-filesystem-ftpext.php
		-
			message: '#expects resource, FTP\\Connection#'
			path: src/wp-admin/includes/class-wp-filesystem-ftpext.php
		-
			identifier: function.internal

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

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Fable 5
Used for: Diagnosing some of the PHPStan level 10 errors and drafting some of the fixes in the final commit; I reviewed, adjusted, and take responsibility for the changes.

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.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y1qB3ZWwGV2nBtdb9NgcJa

… types. As an `ArrayAccess` object, the offsets of `WP_Hook` are hook priorities, which are always integers (or null when appending via `offsetSet()`), and the values are the `Hook_Callback` groups keyed by unique function ID. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add `@return void` to the methods lacking return values, document the callback `$args` arrays as `list<mixed>`, and narrow the `$callback` params of `remove_filter()`/`has_filter()` to `callable`, matching `add_filter()`. In `has_filter()`, pass `0` instead of `false` to `_wp_filter_build_unique_id()`, matching its `int $priority` param. In `apply_filters()`, assign the current priority to a local variable before storing it, and bail from the loop in the (impossible) case that `current()` returns `false`, since `$current_priority` only ever holds integers. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions · 2026-07-07T21:14:31Z

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 johnbillion, westonruter, swissspidy, sergeybiryukov.

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

github-actions · 2026-07-07T21:18:27Z

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.

johnbillion · 2026-07-08T01:23:58Z

-	 *                                         a callback that may or may not exist.
-	 * @param int                   $priority  The exact priority used when adding the original filter callback.
+	 * @param string   $hook_name The filter hook to which the function to be removed is hooked.
+	 * @param callable $callback  The callback to be removed from running when the filter is applied.


This is intentionally wider than callable: 7819ca4

How about bf773c3?

I had to widen the $callback type in _wp_filter_build_unique_id() as well.

SergeyBiryukov · 2026-07-11T22:24:20Z

The new commit:

* Adds `@return void` to the methods lacking return values.

As per the documentation standards, this should generally be avoided:

Note: @return void should not be used outside the default bundled themes and the PHP compatibility shims included in WordPress Core.

That said, it is quite possible that this point is now outdated and should perhaps be reconsidered.

westonruter · 2026-07-11T23:04:32Z

@SergeyBiryukov:

That said, it is quite possible that this point is now outdated and should perhaps be reconsidered.

I think it is obsolete, yes. PHPStan identifies the lack of a return type as an error. New void-returning functions being introduced in core have been using the native void type hint. That said, we could configure PHPStan to ignore the missing return type, but why? Better to be explicit.

Related: There has been cases of void being used in core already which have been replaced with null in unions via Core-64704.

johnbillion · 2026-07-14T12:40:43Z

I agree that refraining from using @return void is outdated, but let's handle that separately from these changes.

johnbillion · 2026-07-14T12:46:41Z

 		}

-		$function_key = _wp_filter_build_unique_id( $hook_name, $callback, false );
+		$function_key = _wp_filter_build_unique_id( $hook_name, $callback, is_int( $priority ) ? $priority : 10 );


The $priority argument is no longer used in _wp_filter_build_unique_id(). Perhaps it should be removed instead.

I was debating whether to do this when working through this. The $hook_name parameter isn't used either, but we can't remove it so easily. My hesitation about removing it is that static analysis with older versions of WP would then flag the lack of the arg as being an error when supplied, or otherwise on newer versions it would flag when it is supplied. I think it's just as well to leave it as-is for now.

johnbillion · 2026-07-14T13:32:48Z

-	 * @param array $args  Additional parameters to pass to the callback functions.
-	 *                     This array is expected to include $value at index 0.
+	 * @param mixed       $value The value to filter.
+	 * @param list<mixed> $args  Additional parameters to pass to the callback functions.


Frustratingly, $args isn't necessarily a list here (although I can see that WP_Hook:: do_action() already documents it as such). The top-level apply_filters() function can be called with the associative array unpacking syntax:

$args = [ 'one' => 1, 'two' => 2, ]; $value = apply_filters( 'foo', 'bar', ...$args );

This causes named parameters to be passed to apply_filters() which results in an associative array of those named parameters being passed to WP_Hook::apply_filters().

I doubt anyone is doing this in real life, but for type safety we need to account for it. Not sure the best approach though. Perhaps $args = array_values( $args )?

Interestingly, in PHP 8 passing an associative array to call_user_func_array() maps the parameters to the corresponding named param in the callback function: https://3v4l.org/GXnqP#veol

When passing the array through apply_filters(), then the mapping is lost, resulting in (apparent) incorrect param: https://3v4l.org/lTFHM#veol

This doesn't work in PHP 8.0 at all. It only starts to work in PHP 8.1. In PHP 7.x, the associative nature of the array is ignored.

Since this didn't work in PHP 7.x and you couldn't pass them in PHP 8.0 either, it seems like now is the time to make sure that $args gets turned into a list to make sure to preserve the expected behavior from PHP 7.

As for how to type apply_filters() so that static analysis flags attempting to spread named parameters into an invocation, I just learned about the @no-named-arguments annotation which does the trick:

apply_filters( 'foo', 'bar', ...array( 'asdasd' => 1 ) );

Function apply_filters invoked with named argument $asdasd, but it's not allowed because of @no-named-arguments.

I've pushed this as bd5a548.

We could add something like this in a function like apply_filters(), do_action(), et al:

/** @var mixed[] $args */ if ( ! array_is_list( $args ) ) { _doing_it_wrong( __FUNCTION__, __( 'Expected args as list.' ), '7.1.0' ); $args = array_values( $args ); }

This might be overkill and it adds another function call in the critical path for WP.

With the latest changes, given the following PHP file:

<?php apply_filters( 'foo', 'bar', ...array( 'baz' => 1 ) ); apply_filters_ref_array( 'foo', array( 'bar', 'baz' => 1, ) ); apply_filters_deprecated( 'foo', array( 'bar', 'baz' => 1, ), '1.0' ); do_action( 'foo', ...array( 'bar' => 1 ) ); do_action_ref_array( 'foo', array( 'bar' => 1, ) ); do_action_deprecated( 'foo', array( 'bar' => 1, ), '1.0' );

PHPStan (rule level 10) is flagging each invocation as having an error:

------ ----------------------------------------------------------------------- Line try-bad-hook-params.php ------ ----------------------------------------------------------------------- 2 Function apply_filters invoked with named argument $baz, but it's not allowed because of @no-named-arguments. 🪪 argument.named at src/wp-content/mu-plugins/try-bad-hook-params.php:2 5 Parameter #2 $args of function apply_filters_ref_array expects list<m ixed>, array{0: 'bar', baz: 1} given. 🪪 argument.type 💡 array{0: 'bar', baz: 1} is not a list. at src/wp-content/mu-plugins/try-bad-hook-params.php:5 12 Parameter #2 $args of function apply_filters_deprecated expects list< mixed>, array{0: 'bar', baz: 1} given. 🪪 argument.type 💡 array{0: 'bar', baz: 1} is not a list. at src/wp-content/mu-plugins/try-bad-hook-params.php:12 19 Function do_action invoked with named argument $bar, but it's not allowed because of @no-named-arguments. 🪪 argument.named at src/wp-content/mu-plugins/try-bad-hook-params.php:19 22 Parameter #2 $args of function do_action_ref_array expects list<mixed >, array{bar: 1} given. 🪪 argument.type 💡 array{bar: 1} is not a list. at src/wp-content/mu-plugins/try-bad-hook-params.php:22 28 Parameter #2 $args of function do_action_deprecated expects list<mixe d>, array{bar: 1} given. 🪪 argument.type 💡 array{bar: 1} is not a list. at src/wp-content/mu-plugins/try-bad-hook-params.php:28 ------ ----------------------------------------------------------------------- [ERROR] Found 6 errors

westonruter · 2026-07-16T02:33:23Z

I agree that refraining from using @return void is outdated, but let's handle that separately from these changes.

Reverted in 199b9ce

…ay not be defined in the current scope.

…which no longer applies.

…filter_build_unique_id()`.

swissspidy · 2026-08-31T09:36:29Z

 			- ../../src/wp-includes/pomo
 			- ../../src/wp-includes/rss.php
 			- ../../src/wp-includes/sodium_compat
+	typeAliases:


TIL! I always defined them locally in a class.

The only problem is it isn't supported by PhpStorm yet 😦

westonruter#6 (comment)

Copilot

Pull request overview

This PR continues the PHPStan type-tightening work around WordPress hooks by removing remaining level-10 issues in WP_Hook and aligning hook-related docblocks/config with the intended callback and args shapes.

Changes:

Introduces a Maybe_Callable PHPStan type alias and uses it to narrow hook callback parameters in docs.
Updates hook API docblocks to describe callback argument arrays as list<mixed> and adds @no-named-arguments to variadic hook functions.
Adjusts WP_Hook::has_filter() / apply_filters() internals to satisfy stricter PHPStan typing, and removes the corresponding PHPStan baseline entry.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
tests/phpstan/baselines/argument.type.neon	Removes the baseline for passing `false` where an `int` is expected in `WP_Hook`.
tests/phpstan/base.neon	Adds a `Maybe_Callable` type alias used by hook-related PHPStan annotations.
src/wp-includes/plugin.php	Tightens hook function docblocks (args lists, callback types) and adds `@no-named-arguments`.
src/wp-includes/class-wp-hook.php	Updates hook method annotations and refactors `has_filter()`/`apply_filters()` to keep types PHPStan-clean.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

westonruter · 2026-08-31T17:35:40Z

+	 * @param mixed       $value The value to filter.
+	 * @param list<mixed> $args  Additional parameters to pass to the callback functions.
+	 *                           This array is expected to include $value at index 0.


Then it should be typed as non-empty-list<mixed> here as well.

🤖 Comment by Claude Opus 5

The observation is right, but the earlier reply on this thread was not: non-empty-list<mixed> is not the correct fix here.

Narrowing WP_Hook::apply_filters() makes PHPStan flag WP_Hook::do_action() for passing list<mixed>, which cascades to do_action_ref_array() and then do_action_deprecated(). That cascade happens to introduce no new errors in core, but it would be inaccurate: wp-cron.php:191 calls do_action_ref_array( $hook, $v['args'] ), and both wp_schedule_event() and wp_schedule_single_event() default $args to array(). Every cron event scheduled without arguments therefore fires do_action_ref_array( $hook, array() ), which covers most core events, wp_version_check and wp_scheduled_delete among them.

The implementation does not require a non-empty array either. On the filter path, index 0 is only ever written — $args[0] = $value at class-wp-hook.php:353, guarded by ! $this->doing_action — and never read; on the action path it is not touched at all. The incoming value at index 0 matters only for count( $args ) at line 339, which is what drives the arity slicing.

So the type stays list<mixed>, and the docblock sentence has been reworded instead in cc601b9:

* @param mixed $value The value to filter. * @param list<mixed> $args Additional parameters to pass to the callback functions. * When filtering, this array is expected to include $value * at index 0. When called for an action by WP_Hook::do_action(), * it contains only the action arguments.

For the record, that sentence predates this PR; only its column alignment was touched here.

…mpty list. `apply_filters_ref_array()` reads `$args[0]` unconditionally, both for the early return when the hook has no callbacks and when passing the value to `WP_Hook`. `apply_filters_deprecated()` returns `$args[0]` when the hook is not registered, and otherwise forwards the array to `apply_filters_ref_array()`. In both cases an empty list is invalid, so `non-empty-list<mixed>` is the accurate type. PHPStan does not report possibly-missing offsets on general array types, so this does not resolve an error inside either function. It takes effect at the call sites, where passing a list that may be empty is now an `argument.type` error. The `do_action` variants are deliberately left as `list<mixed>`: nothing on that path reads index 0, and an empty array is a legitimate argument. `wp-cron.php` calls `do_action_ref_array( $hook, $v['args'] )`, and `wp_schedule_event()` and `wp_schedule_single_event()` both default `$args` to an empty array. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…ex 0 when filtering. The docblock stated unconditionally that `$args` is expected to include `$value` at index 0, which does not hold for the action path: `WP_Hook::do_action()` calls the method with an empty string for `$value` and an array holding only the action arguments. The parameter stays `list<mixed>` rather than narrowing to `non-empty-list<mixed>`, because index 0 is only ever written on the filter path and never read, and is not touched at all on the action path. Its incoming value matters solely for the `count( $args )` that drives the arity slicing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

johnbillion and others added 4 commits July 7, 2026 20:13

Tighten the documented types in WP_Hook.

49e7f6f

Naming.

6e10867

westonruter mentioned this pull request Jul 7, 2026

#64898 Tighten the documented types in WP_Hook #12441

Closed

johnbillion reviewed Jul 8, 2026

View reviewed changes

westonruter added 2 commits July 7, 2026 19:05

Widen $callback type for remove_filter() and has_filter()

bf773c3

Pass in default priority of 10 for unused $priority arg when false

3b5fd8a

westonruter commented Jul 8, 2026

View reviewed changes

Comment thread src/wp-includes/class-wp-hook.php Outdated

Merge branch 'trunk' into fix/wp-hooks-phpstan-level-10-errors

66ff15c

johnbillion reviewed Jul 14, 2026

View reviewed changes

westonruter added 4 commits July 15, 2026 18:05

Merge branch 'trunk' into fix/wp-hooks-phpstan-level-10-errors

97f4432

Remove return void for now

199b9ce

Disallow named arguments on apply_filters() and do_action()

bd5a548

Use list<mixed> consistently on plugin functions

824c89b

westonruter requested a review from johnbillion July 16, 2026 02:37

westonruter and others added 2 commits August 19, 2026 13:31

Merge branch 'trunk' into fix/wp-hooks-phpstan-level-10-errors

f24bbcf

Introduce a Maybe_Callable alias which represents a callable that m…

cdf3f04

…ay not be defined in the current scope.

johnbillion mentioned this pull request Aug 20, 2026

Introduce an alias which represents a callable that may not be defined in the current scope westonruter/wordpress-develop#6

Merged

johnbillion added 3 commits August 24, 2026 03:25

Merge branch 'trunk' into fix/wp-hooks-phpstan-level-10-errors

444d32b

Remove the PHPStan baseline entry for _wp_filter_build_unique_id() …

35d617e

…which no longer applies.

Use the Maybe_Callable alias for the $callback parameter of `_wp_…

2905a7d

…filter_build_unique_id()`.

westonruter requested a review from swissspidy August 28, 2026 17:34

westonruter mentioned this pull request Aug 28, 2026

Code Quality: Add conditional return types for field-plucking functions #13307

Open

swissspidy reviewed Aug 31, 2026

View reviewed changes

westonruter requested a lite review from Copilot August 31, 2026 17:20

Copilot started reviewing on behalf of westonruter August 31, 2026 17:21 View session

Copilot AI reviewed Aug 31, 2026

View reviewed changes

westonruter and others added 2 commits August 31, 2026 12:01

Uh oh!

Conversation

westonruter commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Use of AI Tools

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SergeyBiryukov commented Jul 11, 2026

Uh oh!

westonruter commented Jul 11, 2026

Uh oh!

johnbillion commented Jul 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

westonruter commented Jul 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

westonruter commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading