From 49e7f6f1e421be3e0bfaeee9b28223ad0484a078 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 7 Jul 2026 20:13:29 +0100 Subject: [PATCH 1/3] Tighten the documented types in `WP_Hook`. --- src/wp-includes/class-wp-hook.php | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/src/wp-includes/class-wp-hook.php b/src/wp-includes/class-wp-hook.php index 2ce6ee0a17648..16035f4fc8710 100644 --- a/src/wp-includes/class-wp-hook.php +++ b/src/wp-includes/class-wp-hook.php @@ -14,15 +14,21 @@ * * @see Iterator * @see ArrayAccess + * + * @phpstan-type WP_Hook_Callback array{ + * function: callable, + * accepted_args: int, + * } */ #[AllowDynamicProperties] final class WP_Hook implements Iterator, ArrayAccess { /** - * Hook callbacks. + * Hook callbacks keyed by priority. * * @since 4.7.0 * @var array + * @phpstan-var array> */ public $callbacks = array(); @@ -30,7 +36,7 @@ final class WP_Hook implements Iterator, ArrayAccess { * Priorities list. * * @since 6.4.0 - * @var array + * @var list */ protected $priorities = array(); @@ -38,7 +44,7 @@ final class WP_Hook implements Iterator, ArrayAccess { * The priority keys of actively running iterations of a hook. * * @since 4.7.0 - * @var array + * @var array> */ private $iterations = array(); @@ -46,7 +52,7 @@ final class WP_Hook implements Iterator, ArrayAccess { * The current priority of actively running iterations of a hook. * * @since 4.7.0 - * @var array + * @var array */ private $current_priority = array(); @@ -439,10 +445,11 @@ public function current_priority() { * @since 4.7.0 * * @param array $filters Filters to normalize. See documentation above for details. - * @return WP_Hook[] Array of normalized filters. + * @phpstan-param array>> $filters + * @return array Array of normalized filters keyed by hook name. */ public static function build_preinitialized_hooks( $filters ) { - /** @var WP_Hook[] $normalized */ + /** @var array $normalized */ $normalized = array(); foreach ( $filters as $hook_name => $callback_groups ) { @@ -492,6 +499,7 @@ public function offsetExists( $offset ) { * * @param mixed $offset The offset to retrieve. * @return mixed If set, the value at the specified offset, null otherwise. + * @phpstan-return array|null */ #[ReturnTypeWillChange] public function offsetGet( $offset ) { @@ -541,7 +549,8 @@ public function offsetUnset( $offset ) { * * @link https://www.php.net/manual/en/iterator.current.php * - * @return array Of callbacks at current priority. + * @return array|false Array of callbacks at current priority, false if there are no more elements. + * @phpstan-return array|false */ #[ReturnTypeWillChange] public function current() { @@ -555,7 +564,8 @@ public function current() { * * @link https://www.php.net/manual/en/iterator.next.php * - * @return array Of callbacks at next priority. + * @return array|false Array of callbacks at next priority, false if there are no more elements. + * @phpstan-return array|false */ #[ReturnTypeWillChange] public function next() { @@ -569,7 +579,7 @@ public function next() { * * @link https://www.php.net/manual/en/iterator.key.php * - * @return mixed Returns current priority on success, or NULL on failure + * @return int|null Returns current priority on success, or NULL on failure */ #[ReturnTypeWillChange] public function key() { From 6e10867dd4ac6d1420aef8d992fad255c3c9e879 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 7 Jul 2026 21:07:43 +0100 Subject: [PATCH 2/3] Naming. --- src/wp-includes/class-wp-hook.php | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/wp-includes/class-wp-hook.php b/src/wp-includes/class-wp-hook.php index 16035f4fc8710..2a5825b499cef 100644 --- a/src/wp-includes/class-wp-hook.php +++ b/src/wp-includes/class-wp-hook.php @@ -15,7 +15,7 @@ * @see Iterator * @see ArrayAccess * - * @phpstan-type WP_Hook_Callback array{ + * @phpstan-type Hook_Callback array{ * function: callable, * accepted_args: int, * } @@ -28,7 +28,7 @@ final class WP_Hook implements Iterator, ArrayAccess { * * @since 4.7.0 * @var array - * @phpstan-var array> + * @phpstan-var array> */ public $callbacks = array(); @@ -445,7 +445,7 @@ public function current_priority() { * @since 4.7.0 * * @param array $filters Filters to normalize. See documentation above for details. - * @phpstan-param array>> $filters + * @phpstan-param array>> $filters * @return array Array of normalized filters keyed by hook name. */ public static function build_preinitialized_hooks( $filters ) { @@ -499,7 +499,7 @@ public function offsetExists( $offset ) { * * @param mixed $offset The offset to retrieve. * @return mixed If set, the value at the specified offset, null otherwise. - * @phpstan-return array|null + * @phpstan-return array|null */ #[ReturnTypeWillChange] public function offsetGet( $offset ) { @@ -550,7 +550,7 @@ public function offsetUnset( $offset ) { * @link https://www.php.net/manual/en/iterator.current.php * * @return array|false Array of callbacks at current priority, false if there are no more elements. - * @phpstan-return array|false + * @phpstan-return array|false */ #[ReturnTypeWillChange] public function current() { @@ -565,7 +565,7 @@ public function current() { * @link https://www.php.net/manual/en/iterator.next.php * * @return array|false Array of callbacks at next priority, false if there are no more elements. - * @phpstan-return array|false + * @phpstan-return array|false */ #[ReturnTypeWillChange] public function next() { From 67f3a9bc7e9d658328c6ab13115f54d3e62fbc48 Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Tue, 7 Jul 2026 14:03:03 -0700 Subject: [PATCH 3/3] Document the `Iterator`/`ArrayAccess` generics and tighten the offset 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 --- src/wp-includes/class-wp-hook.php | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/wp-includes/class-wp-hook.php b/src/wp-includes/class-wp-hook.php index 2a5825b499cef..38895c87f1349 100644 --- a/src/wp-includes/class-wp-hook.php +++ b/src/wp-includes/class-wp-hook.php @@ -19,6 +19,9 @@ * function: callable, * accepted_args: int, * } + * + * @phpstan-implements Iterator> + * @phpstan-implements ArrayAccess> */ #[AllowDynamicProperties] final class WP_Hook implements Iterator, ArrayAccess { @@ -482,7 +485,7 @@ public static function build_preinitialized_hooks( $filters ) { * * @link https://www.php.net/manual/en/arrayaccess.offsetexists.php * - * @param mixed $offset An offset to check for. + * @param int $offset An offset to check for. * @return bool True if the offset exists, false otherwise. */ #[ReturnTypeWillChange] @@ -497,8 +500,8 @@ public function offsetExists( $offset ) { * * @link https://www.php.net/manual/en/arrayaccess.offsetget.php * - * @param mixed $offset The offset to retrieve. - * @return mixed If set, the value at the specified offset, null otherwise. + * @param int $offset The offset to retrieve. + * @return array|null If set, the value at the specified offset, null otherwise. * @phpstan-return array|null */ #[ReturnTypeWillChange] @@ -513,8 +516,9 @@ public function offsetGet( $offset ) { * * @link https://www.php.net/manual/en/arrayaccess.offsetset.php * - * @param mixed $offset The offset to assign the value to. - * @param mixed $value The value to set. + * @param int|null $offset The offset to assign the value to. + * @param array $value The value to set. + * @phpstan-param array $value */ #[ReturnTypeWillChange] public function offsetSet( $offset, $value ) { @@ -534,7 +538,7 @@ public function offsetSet( $offset, $value ) { * * @link https://www.php.net/manual/en/arrayaccess.offsetunset.php * - * @param mixed $offset The offset to unset. + * @param int $offset The offset to unset. */ #[ReturnTypeWillChange] public function offsetUnset( $offset ) {