From cdf3f048ed4b6699bbfddd3f9cf37297964f4666 Mon Sep 17 00:00:00 2001
From: John Blackbourn <john@johnblackbourn.com>
Date: Thu, 20 Aug 2026 12:27:28 -0700
Subject: [PATCH] Introduce a `Maybe_Callable` alias which represents a
 callable that may not be defined in the current scope.

---
 src/wp-includes/class-wp-hook.php | 4 ++--
 src/wp-includes/plugin.php        | 4 ++++
 tests/phpstan/base.neon           | 8 ++++++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/wp-includes/class-wp-hook.php b/src/wp-includes/class-wp-hook.php
index d619c9d0c677d..3eb2042d8f0ba 100644
--- a/src/wp-includes/class-wp-hook.php
+++ b/src/wp-includes/class-wp-hook.php
@@ -201,7 +201,7 @@ private function resort_active_iterations( $new_priority = false, $priority_exis
 	 *                                         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
+	 * @phpstan-param Maybe_Callable $callback
 	 */
 	public function remove_filter( $hook_name, $callback, $priority ) {
 		if ( null === $priority ) {
@@ -249,7 +249,7 @@ public function remove_filter( $hook_name, $callback, $priority ) {
 	 *                  of that hook is returned, or false if the function is not attached.
 	 *                  If `$callback` and `$priority` are both provided, a boolean is returned
 	 *                  for whether the specific function is registered at that priority.
-	 * @phpstan-param callable|string|array{ 0: string|object, 1: string, ... }|false $callback
+	 * @phpstan-param Maybe_Callable|false $callback
 	 */
 	public function has_filter( $hook_name = '', $callback = false, $priority = false ) {
 		if ( false === $callback ) {
diff --git a/src/wp-includes/plugin.php b/src/wp-includes/plugin.php
index c8700977799e5..8c78b24f564e9 100644
--- a/src/wp-includes/plugin.php
+++ b/src/wp-includes/plugin.php
@@ -284,6 +284,7 @@ function apply_filters_ref_array( $hook_name, $args ) {
  *                  of that hook is returned, or false if the function is not attached.
  *                  If `$callback` and `$priority` are both provided, a boolean is returned
  *                  for whether the specific function is registered at that priority.
+ * @phpstan-param Maybe_Callable|false $callback
  */
 function has_filter( $hook_name, $callback = false, $priority = false ) {
 	global $wp_filter;
@@ -316,6 +317,7 @@ function has_filter( $hook_name, $callback = false, $priority = false ) {
  * @param int                   $priority  Optional. The exact priority used when adding the original
  *                                         filter callback. Default 10.
  * @return bool Whether the function existed before it was removed.
+ * @phpstan-param Maybe_Callable $callback
  */
 function remove_filter( $hook_name, $callback, $priority = 10 ) {
 	global $wp_filter;
@@ -597,6 +599,7 @@ function do_action_ref_array( $hook_name, $args ) {
  *                  of that hook is returned, or false if the function is not attached.
  *                  If `$callback` and `$priority` are both provided, a boolean is returned
  *                  for whether the specific function is registered at that priority.
+ * @phpstan-param Maybe_Callable|false $callback
  */
 function has_action( $hook_name, $callback = false, $priority = false ) {
 	return has_filter( $hook_name, $callback, $priority );
@@ -621,6 +624,7 @@ function has_action( $hook_name, $callback = false, $priority = false ) {
  * @param int                   $priority  Optional. The exact priority used when adding the original
  *                                         action callback. Default 10.
  * @return bool Whether the function is removed.
+ * @phpstan-param Maybe_Callable $callback
  */
 function remove_action( $hook_name, $callback, $priority = 10 ) {
 	return remove_filter( $hook_name, $callback, $priority );
diff --git a/tests/phpstan/base.neon b/tests/phpstan/base.neon
index ab07051c9ad7a..0d519928c0928 100644
--- a/tests/phpstan/base.neon
+++ b/tests/phpstan/base.neon
@@ -210,3 +210,11 @@ parameters:
 			- ../../src/wp-includes/pomo
 			- ../../src/wp-includes/rss.php
 			- ../../src/wp-includes/sodium_compat
+	typeAliases:
+		# A callable that may not be defined in the current scope.
+		Maybe_Callable: '''
+			callable|string|array{
+				0: string|object,
+				1: string,
+			}
+		'''