Code Quality: Tighten the documented types in WP_Hook.

This adds a `Hook_Callback` PHPStan type to represent the shape of a callback used internally in `WP_Hook` and used in return values of array access methods.

Developed in: WordPress#12441

Props westonruter

See #64898


git-svn-id: https://develop.svn.wordpress.org/trunk@62733 602fd350-edb4-49c9-b593-d223f7449a82

Author: johnbillion

src/wp-includes/class-wp-hook.php

@@ -14,39 +14,48 @@
  *
  * @see Iterator
  * @see ArrayAccess
+ *
+ * @phpstan-type Hook_Callback array{
+ *   function: callable,
+ *   accepted_args: int,
+ * }
+ *
+ * @phpstan-implements Iterator<int, array<string, Hook_Callback>>
+ * @phpstan-implements ArrayAccess<int, array<string, Hook_Callback>>
  */
 #[AllowDynamicProperties]
 final class WP_Hook implements Iterator, ArrayAccess {
 
 	/**
-	 * Hook callbacks.
+	 * Hook callbacks keyed by priority.
 	 *
 	 * @since 4.7.0
 	 * @var array
+	 * @phpstan-var array<int, array<string, Hook_Callback>>
 	 */
 	public $callbacks = array();
 
 	/**
 	 * Priorities list.
 	 *
 	 * @since 6.4.0
-	 * @var array
+	 * @var list<int>
 	 */
 	protected $priorities = array();
 
 	/**
 	 * The priority keys of actively running iterations of a hook.
 	 *
 	 * @since 4.7.0
-	 * @var array
+	 * @var array<int, list<int>>
 	 */
 	private $iterations = array();
 
 	/**
 	 * The current priority of actively running iterations of a hook.
 	 *
 	 * @since 4.7.0
-	 * @var array
+	 * @var array<int, int>
 	 */
 	private $current_priority = array();
 
@@ -439,10 +448,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<string, WP_Hook|array<int, array<Hook_Callback>>> $filters
+	 * @return array<string, WP_Hook> Array of normalized filters keyed by hook name.
 	 */
 	public static function build_preinitialized_hooks( $filters ) {
-		/** @var WP_Hook[] $normalized */
+		/** @var array<string, WP_Hook> $normalized */
 		$normalized = array();
 
 		foreach ( $filters as $hook_name => $callback_groups ) {
@@ -475,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]
@@ -490,8 +500,9 @@ 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<string, Hook_Callback>|null
 	 */
 	#[ReturnTypeWillChange]
 	public function offsetGet( $offset ) {
@@ -505,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<string, Hook_Callback> $value
 	 */
 	#[ReturnTypeWillChange]
 	public function offsetSet( $offset, $value ) {
@@ -526,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 ) {
@@ -541,7 +553,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<string, Hook_Callback>|false
 	 */
 	#[ReturnTypeWillChange]
 	public function current() {
@@ -555,7 +568,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<string, Hook_Callback>|false
 	 */
 	#[ReturnTypeWillChange]
 	public function next() {
@@ -569,7 +583,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() {