#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/64898

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, 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.

westonruter · 2026-07-08T02:13:57Z

 	 *                                         a callback that may or may not exist.
 	 * @param int                   $priority  The exact priority used when adding the original filter callback.
 	 * @return bool Whether the callback existed before it was removed.
+	 * @phpstan-param callable|string|array{ 0: string|object, 1: string, ... } $callback


I chose array{ 0: string|object, 1: string, ... } as the array shape for the $callback because this is the array shape required by _wp_filter_build_unique_id() or else it will return null.

How about encapsulating callable|string|array{ 0: string|object, 1: string, ... } into a PHPStan type on the class with a name that makes it clear what it represents? eg:

@phpstan-type Maybe_Callable callable|string|array{ 0: string|object, 1: string }

I don't believe the trailing ... is necessary on the array either. A callable array will only every have two elements, the class name or object and the method name.

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.

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 )?

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

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

66ff15c

johnbillion reviewed Jul 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

#64896 Fix remaining PHPStan level 10 errors in `WP_Hook`#12443

#64896 Fix remaining PHPStan level 10 errors in `WP_Hook`#12443
westonruter wants to merge 7 commits into
WordPress:trunkfrom
westonruter:fix/wp-hooks-phpstan-level-10-errors

westonruter commented Jul 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 7, 2026

Uh oh!

johnbillion Jul 8, 2026

Uh oh!

westonruter Jul 8, 2026

Uh oh!

westonruter Jul 8, 2026

Uh oh!

westonruter Jul 8, 2026

Uh oh!

johnbillion Jul 14, 2026

Uh oh!

SergeyBiryukov commented Jul 11, 2026

Uh oh!

westonruter commented Jul 11, 2026

Uh oh!

johnbillion commented Jul 14, 2026

Uh oh!

johnbillion Jul 14, 2026

Uh oh!

johnbillion Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

johnbillion Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

johnbillion Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

SergeyBiryukov commented Jul 11, 2026

Uh oh!

westonruter commented Jul 11, 2026

Uh oh!

johnbillion commented Jul 14, 2026

Uh oh!

johnbillion Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

johnbillion Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

westonruter commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading