From f8b11d7cb15ae5b9aeeb8ae0bb7bebb8ec8898b5 Mon Sep 17 00:00:00 2001
From: Pascal Birchler <pascal.birchler@gmail.com>
Date: Thu, 1 Oct 2026 08:53:28 +0000
Subject: [PATCH 1/5] Docs: Add PHPStan types for optional callback parameters.

The `add_*_page()` functions, and the `Custom_Background` and `Custom_Image_Header` constructors, default their callback to an empty string, which a plain `callable` does not allow. Their `@phpstan-param` now allows `''` and `null`, the latter because plugins and the Customizer commonly pass it. `unregister_setting()` narrows its deprecated third parameter to `''` in the same way.

The activation, deactivation, uninstall and feed callbacks gain the signature core calls them with.

This empties the `parameter.defaultValue` baseline, which is removed.

See #65817.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VieGtSQtUoVfHiGwTmkvtc
---
 phpstan.neon.dist                             |   1 -
 .../includes/class-custom-background.php      |   7 ++
 .../includes/class-custom-image-header.php    |   6 +
 src/wp-admin/includes/plugin.php              |  26 +++++
 src/wp-includes/option.php                    |   2 +
 src/wp-includes/plugin.php                    |   6 +
 src/wp-includes/rewrite.php                   |   2 +
 .../baselines/parameter.defaultValue.neon     | 105 ------------------
 8 files changed, 49 insertions(+), 106 deletions(-)
 delete mode 100644 tests/phpstan/baselines/parameter.defaultValue.neon

diff --git a/phpstan.neon.dist b/phpstan.neon.dist
index 8c498f1121e8a..6db93188dda4b 100644
--- a/phpstan.neon.dist
+++ b/phpstan.neon.dist
@@ -59,7 +59,6 @@ includes:
 	- tests/phpstan/baselines/offsetAccess.nonOffsetAccessible.neon
 	- tests/phpstan/baselines/offsetAccess.notFound.neon
 	- tests/phpstan/baselines/offsetAssign.valueType.neon
-	- tests/phpstan/baselines/parameter.defaultValue.neon
 	- tests/phpstan/baselines/parameter.notFound.neon
 	- tests/phpstan/baselines/parameterByRef.type.neon
 	- tests/phpstan/baselines/parameterByRef.unusedType.neon
diff --git a/src/wp-admin/includes/class-custom-background.php b/src/wp-admin/includes/class-custom-background.php
index 7f8f23485086a..fc9bc8751e8a0 100644
--- a/src/wp-admin/includes/class-custom-background.php
+++ b/src/wp-admin/includes/class-custom-background.php
@@ -19,6 +19,8 @@ class Custom_Background {
 	 *
 	 * @since 3.0.0
 	 * @var callable
+	 *
+	 * @phpstan-var ''|(callable(): mixed)|null
 	 */
 	public $admin_header_callback;
 
@@ -27,6 +29,8 @@ class Custom_Background {
 	 *
 	 * @since 3.0.0
 	 * @var callable
+	 *
+	 * @phpstan-var ''|(callable(): mixed)|null
 	 */
 	public $admin_image_div_callback;
 
@@ -47,6 +51,9 @@ class Custom_Background {
 	 *                                           Default empty string.
 	 * @param callable $admin_image_div_callback Optional. Custom image div output callback.
 	 *                                           Default empty string.
+	 *
+	 * @phpstan-param ''|(callable(): mixed)|null $admin_header_callback
+	 * @phpstan-param ''|(callable(): mixed)|null $admin_image_div_callback
 	 */
 	public function __construct( $admin_header_callback = '', $admin_image_div_callback = '' ) {
 		$this->admin_header_callback    = $admin_header_callback;
diff --git a/src/wp-admin/includes/class-custom-image-header.php b/src/wp-admin/includes/class-custom-image-header.php
index 367ba04cdc340..ec95fd43f7d6c 100644
--- a/src/wp-admin/includes/class-custom-image-header.php
+++ b/src/wp-admin/includes/class-custom-image-header.php
@@ -19,6 +19,8 @@ class Custom_Image_Header {
 	 *
 	 * @since 2.1.0
 	 * @var callable
+	 *
+	 * @phpstan-var ''|(callable(): mixed)|null
 	 */
 	public $admin_header_callback;
 
@@ -27,6 +29,8 @@ class Custom_Image_Header {
 	 *
 	 * @since 3.0.0
 	 * @var callable
+	 *
+	 * @phpstan-var ''|(callable(): mixed)|null
 	 */
 	public $admin_image_div_callback;
 
@@ -54,6 +58,8 @@ class Custom_Image_Header {
 	 * @param callable $admin_header_callback    Administration header callback.
 	 * @param callable $admin_image_div_callback Optional. Custom image div output callback.
 	 *                                           Default empty string.
+	 *
+	 * @phpstan-param ''|(callable(): mixed)|null $admin_image_div_callback
 	 */
 	public function __construct( $admin_header_callback, $admin_image_div_callback = '' ) {
 		$this->admin_header_callback    = $admin_header_callback;
diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index a34d473bca650..ae59ff8ad2d56 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -1398,6 +1398,8 @@ function uninstall_plugin( $plugin ) {
  *                              * Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS.
  * @param int|float $position   Optional. The position in the menu order this item should appear.
  * @return string The resulting page's hook_suffix.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $icon_url = '', $position = null ) {
 	global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;
@@ -1493,6 +1495,8 @@ function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $call
  * @param callable  $callback    Optional. The function to be called to output the content for this page.
  * @param int|float $position    Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,
@@ -1606,6 +1610,8 @@ function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability,
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1630,6 +1636,8 @@ function add_management_page( $page_title, $menu_title, $capability, $menu_slug,
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1654,6 +1662,8 @@ function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $c
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1678,6 +1688,8 @@ function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1702,6 +1714,8 @@ function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $c
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	if ( current_user_can( 'edit_users' ) ) {
@@ -1731,6 +1745,8 @@ function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1755,6 +1771,8 @@ function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug,
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1779,6 +1797,8 @@ function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1803,6 +1823,8 @@ function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1827,6 +1849,8 @@ function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1851,6 +1875,8 @@ function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param callable $callback   Optional. The function to be called to output the content for this page.
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
+ *
+ * @phpstan-param ''|callable|null $callback
  */
 function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
diff --git a/src/wp-includes/option.php b/src/wp-includes/option.php
index d5c179c645af3..8dc60211294b2 100644
--- a/src/wp-includes/option.php
+++ b/src/wp-includes/option.php
@@ -3119,6 +3119,8 @@ function register_setting( $option_group, $option_name, $args = array() ) {
  * @param string   $option_group The settings group name used during registration.
  * @param string   $option_name  The name of the option to unregister.
  * @param callable $deprecated   Optional. Deprecated.
+ *
+ * @phpstan-param '' $deprecated
  */
 function unregister_setting( $option_group, $option_name, $deprecated = '' ) {
 	global $new_allowed_options, $wp_registered_settings;
diff --git a/src/wp-includes/plugin.php b/src/wp-includes/plugin.php
index a3e9afacdb8dc..197677ec79606 100644
--- a/src/wp-includes/plugin.php
+++ b/src/wp-includes/plugin.php
@@ -896,6 +896,8 @@ function plugin_dir_url( $file ) {
  *
  * @param string   $file     The filename of the plugin including the path.
  * @param callable $callback The function hooked to the 'activate_PLUGIN' action.
+ *
+ * @phpstan-param callable(bool): mixed $callback
  */
 function register_activation_hook( $file, $callback ) {
 	$file = plugin_basename( $file );
@@ -919,6 +921,8 @@ function register_activation_hook( $file, $callback ) {
  *
  * @param string   $file     The filename of the plugin including the path.
  * @param callable $callback The function hooked to the 'deactivate_PLUGIN' action.
+ *
+ * @phpstan-param callable(bool): mixed $callback
  */
 function register_deactivation_hook( $file, $callback ) {
 	$file = plugin_basename( $file );
@@ -950,6 +954,8 @@ function register_deactivation_hook( $file, $callback ) {
  * @param string   $file     Plugin file.
  * @param callable $callback The callback to run when the hook is called. Must be
  *                           a static method or function.
+ *
+ * @phpstan-param callable(): mixed $callback
  */
 function register_uninstall_hook( $file, $callback ) {
 	if ( is_array( $callback ) && is_object( $callback[0] ) ) {
diff --git a/src/wp-includes/rewrite.php b/src/wp-includes/rewrite.php
index 976d2a014b9db..899bbebfe60e8 100644
--- a/src/wp-includes/rewrite.php
+++ b/src/wp-includes/rewrite.php
@@ -247,6 +247,8 @@ function remove_permastruct( $name ) {
  * @param string   $feedname Feed name. Should not start with '_'.
  * @param callable $callback Callback to run on feed display.
  * @return string Feed action name.
+ *
+ * @phpstan-param callable(bool, string): mixed $callback
  */
 function add_feed( $feedname, $callback ) {
 	global $wp_rewrite;
diff --git a/tests/phpstan/baselines/parameter.defaultValue.neon b/tests/phpstan/baselines/parameter.defaultValue.neon
deleted file mode 100644
index 34b6b678fc447..0000000000000
--- a/tests/phpstan/baselines/parameter.defaultValue.neon
+++ /dev/null
@@ -1,105 +0,0 @@
-# PHPStan baseline for the `parameter.defaultValue` errors in WordPress core.
-#
-# https://phpstan.org/error-identifiers/parameter.defaultValue
-#
-# Each entry is scoped to a single file and carries an exact occurrence count,
-# so that a new instance is reported as a new error rather than being absorbed
-# silently. Fixing an occurrence therefore means decrementing or removing its
-# entry here as part of the same change.
-#
-# The goal is to empty this file and delete it, along with the `includes` entry
-# for it in phpstan.neon.dist.
-#
-# Generated by `composer phpstan:baselines`. Do not edit by hand; regenerate with
-#
-#     composer phpstan:baselines -- --identifier=parameter.defaultValue
-#
-# which reruns the analysis with this file suppressed so the errors surface again.
-
-parameters:
-	ignoreErrors:
-		-
-			message: '#^Default value of the parameter \#1 \$admin_header_callback \(''''\) of method Custom_Background\:\:__construct\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/class-custom-background.php
-		-
-			message: '#^Default value of the parameter \#2 \$admin_image_div_callback \(''''\) of method Custom_Background\:\:__construct\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/class-custom-background.php
-		-
-			message: '#^Default value of the parameter \#2 \$admin_image_div_callback \(''''\) of method Custom_Image_Header\:\:__construct\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/class-custom-image-header.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_comments_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_dashboard_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_links_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_management_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_media_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_menu_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_options_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_pages_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_plugins_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_posts_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_theme_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#5 \$callback \(''''\) of function add_users_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#6 \$callback \(''''\) of function add_submenu_page\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-admin/includes/plugin.php
-		-
-			message: '#^Default value of the parameter \#3 \$deprecated \(''''\) of function unregister_setting\(\) is incompatible with type callable\(\)\: mixed\.$#'
-			identifier: parameter.defaultValue
-			count: 1
-			path: ../../../src/wp-includes/option.php

From 6103aaa2a68c05e3019e30dba29612ee46fe3ada Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 5 Oct 2026 15:58:45 +0000
Subject: [PATCH 2/5] Docs: Address review feedback on callback types.

Allow null and an empty string for the $admin_header_callback parameter of Custom_Image_Header::__construct(), since the Customizer and the theme-support defaults pass them. Also type the admin page callbacks as callable(): mixed, matching Custom_Image_Header and Custom_Background, since the page hook is fired without arguments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015BuoHZQvJMvPEYp4Sfjgvd
---
 .../includes/class-custom-image-header.php    |  1 +
 src/wp-admin/includes/plugin.php              | 26 +++++++++----------
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/src/wp-admin/includes/class-custom-image-header.php b/src/wp-admin/includes/class-custom-image-header.php
index ec95fd43f7d6c..6f207469b1e1a 100644
--- a/src/wp-admin/includes/class-custom-image-header.php
+++ b/src/wp-admin/includes/class-custom-image-header.php
@@ -59,6 +59,7 @@ class Custom_Image_Header {
 	 * @param callable $admin_image_div_callback Optional. Custom image div output callback.
 	 *                                           Default empty string.
 	 *
+	 * @phpstan-param ''|(callable(): mixed)|null $admin_header_callback
 	 * @phpstan-param ''|(callable(): mixed)|null $admin_image_div_callback
 	 */
 	public function __construct( $admin_header_callback, $admin_image_div_callback = '' ) {
diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index ae59ff8ad2d56..fb8cb4c1f7b83 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -1399,7 +1399,7 @@ function uninstall_plugin( $plugin ) {
  * @param int|float $position   Optional. The position in the menu order this item should appear.
  * @return string The resulting page's hook_suffix.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $icon_url = '', $position = null ) {
 	global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;
@@ -1496,7 +1496,7 @@ function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $call
  * @param int|float $position    Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,
@@ -1611,7 +1611,7 @@ function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability,
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1637,7 +1637,7 @@ function add_management_page( $page_title, $menu_title, $capability, $menu_slug,
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1663,7 +1663,7 @@ function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $c
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1689,7 +1689,7 @@ function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1715,7 +1715,7 @@ function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $c
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	if ( current_user_can( 'edit_users' ) ) {
@@ -1746,7 +1746,7 @@ function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1772,7 +1772,7 @@ function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug,
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1798,7 +1798,7 @@ function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1824,7 +1824,7 @@ function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1850,7 +1850,7 @@ function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1876,7 +1876,7 @@ function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|callable|null $callback
+ * @phpstan-param ''|(callable(): mixed)|null $callback
  */
 function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );

From 8e753709ebe76338277dc5cfa63ee19144484599 Mon Sep 17 00:00:00 2001
From: Pascal Birchler <pascal.birchler@gmail.com>
Date: Wed, 7 Oct 2026 08:47:35 +0200
Subject: [PATCH 3/5] Update src/wp-includes/rewrite.php

Co-authored-by: Weston Ruter <westonruter@gmail.com>
---
 src/wp-includes/rewrite.php | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/wp-includes/rewrite.php b/src/wp-includes/rewrite.php
index 899bbebfe60e8..a62f8d9c3b9d8 100644
--- a/src/wp-includes/rewrite.php
+++ b/src/wp-includes/rewrite.php
@@ -248,7 +248,8 @@ function remove_permastruct( $name ) {
  * @param callable $callback Callback to run on feed display.
  * @return string Feed action name.
  *
- * @phpstan-param callable(bool, string): mixed $callback
+ * @phpstan-param non-empty-string                        $feedname
+ * @phpstan-param callable(bool, non-empty-string): mixed $callback
  */
 function add_feed( $feedname, $callback ) {
 	global $wp_rewrite;

From 8b7e5017727c2d6d5f28880ba1457a1ec9607caf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 7 Oct 2026 12:20:40 +0000
Subject: [PATCH 4/5] Docs: Address review feedback on PHPStan callback types.

- Add an `Optional_Callback` type alias to `base.neon` and use it for the
  `add_*_page()` callbacks and the `Custom_Background` and
  `Custom_Image_Header` callbacks, instead of repeating the union.
- Document those `Custom_*` callbacks as `callable|string|null` in the plain
  `@var` and `@param` tags too, so IDEs and the developer reference see the
  empty string and `null` that core passes.
- Type `unregister_setting()`'s deprecated `$deprecated` parameter as
  `''|callable`, since the function still handles a callable.
- Restrict `register_uninstall_hook()`'s callback to a function name or a
  static `[ClassName, 'method']` pair, as the docblock requires. Closures
  cannot be serialized into the `uninstall_plugins` option, and instance
  methods are rejected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BL6dYS5ydouQDBQmjem93A
---
 .../includes/class-custom-background.php      | 20 +++++++-------
 .../includes/class-custom-image-header.php    | 19 +++++++-------
 src/wp-admin/includes/plugin.php              | 26 +++++++++----------
 src/wp-includes/option.php                    |  2 +-
 src/wp-includes/plugin.php                    |  2 +-
 tests/phpstan/base.neon                       |  6 +++++
 6 files changed, 41 insertions(+), 34 deletions(-)

diff --git a/src/wp-admin/includes/class-custom-background.php b/src/wp-admin/includes/class-custom-background.php
index fc9bc8751e8a0..c910f46f1d874 100644
--- a/src/wp-admin/includes/class-custom-background.php
+++ b/src/wp-admin/includes/class-custom-background.php
@@ -18,9 +18,9 @@ class Custom_Background {
 	 * Callback for administration header.
 	 *
 	 * @since 3.0.0
-	 * @var callable
+	 * @var callable|string|null
 	 *
-	 * @phpstan-var ''|(callable(): mixed)|null
+	 * @phpstan-var Optional_Callback
 	 */
 	public $admin_header_callback;
 
@@ -28,9 +28,9 @@ class Custom_Background {
 	 * Callback for header div.
 	 *
 	 * @since 3.0.0
-	 * @var callable
+	 * @var callable|string|null
 	 *
-	 * @phpstan-var ''|(callable(): mixed)|null
+	 * @phpstan-var Optional_Callback
 	 */
 	public $admin_image_div_callback;
 
@@ -47,13 +47,13 @@ class Custom_Background {
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param callable $admin_header_callback    Optional. Administration header callback.
-	 *                                           Default empty string.
-	 * @param callable $admin_image_div_callback Optional. Custom image div output callback.
-	 *                                           Default empty string.
+	 * @param callable|string|null $admin_header_callback    Optional. Administration header callback.
+	 *                                                       Default empty string.
+	 * @param callable|string|null $admin_image_div_callback Optional. Custom image div output callback.
+	 *                                                       Default empty string.
 	 *
-	 * @phpstan-param ''|(callable(): mixed)|null $admin_header_callback
-	 * @phpstan-param ''|(callable(): mixed)|null $admin_image_div_callback
+	 * @phpstan-param Optional_Callback $admin_header_callback
+	 * @phpstan-param Optional_Callback $admin_image_div_callback
 	 */
 	public function __construct( $admin_header_callback = '', $admin_image_div_callback = '' ) {
 		$this->admin_header_callback    = $admin_header_callback;
diff --git a/src/wp-admin/includes/class-custom-image-header.php b/src/wp-admin/includes/class-custom-image-header.php
index 6f207469b1e1a..7a4437e2ea509 100644
--- a/src/wp-admin/includes/class-custom-image-header.php
+++ b/src/wp-admin/includes/class-custom-image-header.php
@@ -18,9 +18,9 @@ class Custom_Image_Header {
 	 * Callback for administration header.
 	 *
 	 * @since 2.1.0
-	 * @var callable
+	 * @var callable|string|null
 	 *
-	 * @phpstan-var ''|(callable(): mixed)|null
+	 * @phpstan-var Optional_Callback
 	 */
 	public $admin_header_callback;
 
@@ -28,9 +28,9 @@ class Custom_Image_Header {
 	 * Callback for header div.
 	 *
 	 * @since 3.0.0
-	 * @var callable
+	 * @var callable|string|null
 	 *
-	 * @phpstan-var ''|(callable(): mixed)|null
+	 * @phpstan-var Optional_Callback
 	 */
 	public $admin_image_div_callback;
 
@@ -55,12 +55,13 @@ class Custom_Image_Header {
 	 *
 	 * @since 2.1.0
 	 *
-	 * @param callable $admin_header_callback    Administration header callback.
-	 * @param callable $admin_image_div_callback Optional. Custom image div output callback.
-	 *                                           Default empty string.
+	 * @param callable|string|null $admin_header_callback    Administration header callback.
+	 *                                                       Empty string or null for none.
+	 * @param callable|string|null $admin_image_div_callback Optional. Custom image div output callback.
+	 *                                                       Default empty string.
 	 *
-	 * @phpstan-param ''|(callable(): mixed)|null $admin_header_callback
-	 * @phpstan-param ''|(callable(): mixed)|null $admin_image_div_callback
+	 * @phpstan-param Optional_Callback $admin_header_callback
+	 * @phpstan-param Optional_Callback $admin_image_div_callback
 	 */
 	public function __construct( $admin_header_callback, $admin_image_div_callback = '' ) {
 		$this->admin_header_callback    = $admin_header_callback;
diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index 90272692821f9..81dd3e2097552 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -1400,7 +1400,7 @@ function uninstall_plugin( $plugin ) {
  * @param int|float $position   Optional. The position in the menu order this item should appear.
  * @return string The resulting page's hook_suffix.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $icon_url = '', $position = null ) {
 	global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;
@@ -1497,7 +1497,7 @@ function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $call
  * @param int|float $position    Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,
@@ -1612,7 +1612,7 @@ function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability,
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1638,7 +1638,7 @@ function add_management_page( $page_title, $menu_title, $capability, $menu_slug,
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1664,7 +1664,7 @@ function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $c
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1690,7 +1690,7 @@ function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1716,7 +1716,7 @@ function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $c
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	if ( current_user_can( 'edit_users' ) ) {
@@ -1747,7 +1747,7 @@ function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1773,7 +1773,7 @@ function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug,
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1799,7 +1799,7 @@ function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1825,7 +1825,7 @@ function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1851,7 +1851,7 @@ function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1877,7 +1877,7 @@ function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @param int      $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param ''|(callable(): mixed)|null $callback
+ * @phpstan-param Optional_Callback $callback
  */
 function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
diff --git a/src/wp-includes/option.php b/src/wp-includes/option.php
index 2a2daff64e750..b25caae0cfe8f 100644
--- a/src/wp-includes/option.php
+++ b/src/wp-includes/option.php
@@ -3124,7 +3124,7 @@ function register_setting( $option_group, $option_name, $args = array() ) {
  * @param string   $option_name  The name of the option to unregister.
  * @param callable $deprecated   Optional. Deprecated.
  *
- * @phpstan-param '' $deprecated
+ * @phpstan-param ''|callable $deprecated
  */
 function unregister_setting( $option_group, $option_name, $deprecated = '' ) {
 	global $new_allowed_options, $wp_registered_settings;
diff --git a/src/wp-includes/plugin.php b/src/wp-includes/plugin.php
index 197677ec79606..23d8351bd90b3 100644
--- a/src/wp-includes/plugin.php
+++ b/src/wp-includes/plugin.php
@@ -955,7 +955,7 @@ function register_deactivation_hook( $file, $callback ) {
  * @param callable $callback The callback to run when the hook is called. Must be
  *                           a static method or function.
  *
- * @phpstan-param callable(): mixed $callback
+ * @phpstan-param (callable-string|array{class-string, non-empty-string})&(callable(): mixed) $callback
  */
 function register_uninstall_hook( $file, $callback ) {
 	if ( is_array( $callback ) && is_object( $callback[0] ) ) {
diff --git a/tests/phpstan/base.neon b/tests/phpstan/base.neon
index 4f1f4d4f7be4b..eddb4c611752c 100644
--- a/tests/phpstan/base.neon
+++ b/tests/phpstan/base.neon
@@ -281,6 +281,12 @@ parameters:
 			}
 		'''
 
+		# An optional callback that is called without arguments, such as an admin page or
+		# custom header callback. Core treats an empty string or null as no callback.
+		Optional_Callback: '''
+			''|(callable(): mixed)|null
+		'''
+
 		# The properties of a block style as WP_Block_Styles_Registry stores them, which is
 		# more than its register() hash accepts: `name` is required for a style to be
 		# registered at all, and `label` is filled in from the name when the caller omits

From 3cf0176dcbb6990a2add9e9a5bc2bacc46d543f9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 07:32:06 +0000
Subject: [PATCH 5/5] Docs: Address further review feedback on PHPStan callback
 types.

- Rename the `Optional_Callback` type alias to `WP_Optional_Callback` to avoid collisions with aliases defined elsewhere.
- Widen the plain `@param` tags for the `add_*_page()` callbacks to `callable|string|null`, like the `Custom_*` classes.
- Note that an empty string or null means no callback in the `Custom_Background` and `Custom_Image_Header` constructor descriptions.
- Narrow `unregister_setting()`'s deprecated parameter to `''`, and document it as a string.

See #65817.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T3XYNUvB9sQNDXA14uJQeH
---
 .../includes/class-custom-background.php      |  12 +-
 .../includes/class-custom-image-header.php    |  10 +-
 src/wp-admin/includes/plugin.php              | 234 +++++++++---------
 src/wp-includes/option.php                    |   8 +-
 tests/phpstan/base.neon                       |   2 +-
 5 files changed, 133 insertions(+), 133 deletions(-)

diff --git a/src/wp-admin/includes/class-custom-background.php b/src/wp-admin/includes/class-custom-background.php
index c910f46f1d874..c8b686d27d6fc 100644
--- a/src/wp-admin/includes/class-custom-background.php
+++ b/src/wp-admin/includes/class-custom-background.php
@@ -20,7 +20,7 @@ class Custom_Background {
 	 * @since 3.0.0
 	 * @var callable|string|null
 	 *
-	 * @phpstan-var Optional_Callback
+	 * @phpstan-var WP_Optional_Callback
 	 */
 	public $admin_header_callback;
 
@@ -30,7 +30,7 @@ class Custom_Background {
 	 * @since 3.0.0
 	 * @var callable|string|null
 	 *
-	 * @phpstan-var Optional_Callback
+	 * @phpstan-var WP_Optional_Callback
 	 */
 	public $admin_image_div_callback;
 
@@ -48,12 +48,12 @@ class Custom_Background {
 	 * @since 3.0.0
 	 *
 	 * @param callable|string|null $admin_header_callback    Optional. Administration header callback.
-	 *                                                       Default empty string.
+	 *                                                       Empty string or null for none. Default empty string.
 	 * @param callable|string|null $admin_image_div_callback Optional. Custom image div output callback.
-	 *                                                       Default empty string.
+	 *                                                       Empty string or null for none. Default empty string.
 	 *
-	 * @phpstan-param Optional_Callback $admin_header_callback
-	 * @phpstan-param Optional_Callback $admin_image_div_callback
+	 * @phpstan-param WP_Optional_Callback $admin_header_callback
+	 * @phpstan-param WP_Optional_Callback $admin_image_div_callback
 	 */
 	public function __construct( $admin_header_callback = '', $admin_image_div_callback = '' ) {
 		$this->admin_header_callback    = $admin_header_callback;
diff --git a/src/wp-admin/includes/class-custom-image-header.php b/src/wp-admin/includes/class-custom-image-header.php
index 7a4437e2ea509..e31919d5945cc 100644
--- a/src/wp-admin/includes/class-custom-image-header.php
+++ b/src/wp-admin/includes/class-custom-image-header.php
@@ -20,7 +20,7 @@ class Custom_Image_Header {
 	 * @since 2.1.0
 	 * @var callable|string|null
 	 *
-	 * @phpstan-var Optional_Callback
+	 * @phpstan-var WP_Optional_Callback
 	 */
 	public $admin_header_callback;
 
@@ -30,7 +30,7 @@ class Custom_Image_Header {
 	 * @since 3.0.0
 	 * @var callable|string|null
 	 *
-	 * @phpstan-var Optional_Callback
+	 * @phpstan-var WP_Optional_Callback
 	 */
 	public $admin_image_div_callback;
 
@@ -58,10 +58,10 @@ class Custom_Image_Header {
 	 * @param callable|string|null $admin_header_callback    Administration header callback.
 	 *                                                       Empty string or null for none.
 	 * @param callable|string|null $admin_image_div_callback Optional. Custom image div output callback.
-	 *                                                       Default empty string.
+	 *                                                       Empty string or null for none. Default empty string.
 	 *
-	 * @phpstan-param Optional_Callback $admin_header_callback
-	 * @phpstan-param Optional_Callback $admin_image_div_callback
+	 * @phpstan-param WP_Optional_Callback $admin_header_callback
+	 * @phpstan-param WP_Optional_Callback $admin_image_div_callback
 	 */
 	public function __construct( $admin_header_callback, $admin_image_div_callback = '' ) {
 		$this->admin_header_callback    = $admin_header_callback;
diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index 36ee46eb52296..cedc7e49a89f6 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -1384,24 +1384,24 @@ function uninstall_plugin( $plugin ) {
  * @global array $_registered_pages
  * @global array $_parent_pages
  *
- * @param string    $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string    $menu_title The text to be used for the menu.
- * @param string    $capability The capability required for this menu to be displayed to the user.
- * @param string    $menu_slug  The slug name to refer to this menu by. Should be unique for this menu page and only
- *                              include lowercase alphanumeric, dashes, and underscores characters to be compatible
- *                              with sanitize_key().
- * @param callable  $callback   Optional. The function to be called to output the content for this page.
- * @param string    $icon_url   Optional. The URL to the icon to be used for this menu.
- *                              * Pass a base64-encoded SVG using a data URI, which will be colored to match
- *                                the color scheme. This should begin with 'data:image/svg+xml;base64,'.
- *                              * Pass the name of a Dashicons helper class to use a font icon,
- *                                e.g. 'dashicons-chart-pie'.
- *                              * Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS.
- * @param int|float $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by. Should be unique for this menu page and only
+ *                                         include lowercase alphanumeric, dashes, and underscores characters to be compatible
+ *                                         with sanitize_key().
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param string               $icon_url   Optional. The URL to the icon to be used for this menu.
+ *                                         * Pass a base64-encoded SVG using a data URI, which will be colored to match
+ *                                           the color scheme. This should begin with 'data:image/svg+xml;base64,'.
+ *                                         * Pass the name of a Dashicons helper class to use a font icon,
+ *                                           e.g. 'dashicons-chart-pie'.
+ *                                         * Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS.
+ * @param int|float            $position   Optional. The position in the menu order this item should appear.
  * @return string The resulting page's hook_suffix.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $icon_url = '', $position = null ) {
 	global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;
@@ -1485,21 +1485,21 @@ function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $call
  * @global array $_registered_pages
  * @global array $_parent_pages
  *
- * @param string    $parent_slug The slug name for the parent menu (or the file name of a standard
- *                               WordPress admin page).
- * @param string    $page_title  The text to be displayed in the title tags of the page when the menu
- *                               is selected.
- * @param string    $menu_title  The text to be used for the menu.
- * @param string    $capability  The capability required for this menu to be displayed to the user.
- * @param string    $menu_slug   The slug name to refer to this menu by. Should be unique for this menu
- *                               and only include lowercase alphanumeric, dashes, and underscores characters
- *                               to be compatible with sanitize_key().
- * @param callable  $callback    Optional. The function to be called to output the content for this page.
- * @param int|float $position    Optional. The position in the menu order this item should appear.
+ * @param string               $parent_slug The slug name for the parent menu (or the file name of a standard
+ *                                          WordPress admin page).
+ * @param string               $page_title  The text to be displayed in the title tags of the page when the menu
+ *                                          is selected.
+ * @param string               $menu_title  The text to be used for the menu.
+ * @param string               $capability  The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug   The slug name to refer to this menu by. Should be unique for this menu
+ *                                          and only include lowercase alphanumeric, dashes, and underscores characters
+ *                                          to be compatible with sanitize_key().
+ * @param callable|string|null $callback    Optional. The function to be called to output the content for this page.
+ * @param int|float            $position    Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,
@@ -1606,16 +1606,16 @@ function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability,
  * @since 1.5.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1633,16 +1633,16 @@ function add_management_page( $page_title, $menu_title, $capability, $menu_slug,
  * @since 1.5.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1660,16 +1660,16 @@ function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $c
  * @since 2.0.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1687,16 +1687,16 @@ function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @since 3.0.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1714,16 +1714,16 @@ function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $c
  * @since 2.1.3
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	if ( current_user_can( 'edit_users' ) ) {
@@ -1746,16 +1746,16 @@ function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @since 2.7.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1773,16 +1773,16 @@ function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug,
  * @since 2.7.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1800,16 +1800,16 @@ function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @since 2.7.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1827,16 +1827,16 @@ function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @since 2.7.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1854,16 +1854,16 @@ function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @since 2.7.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
@@ -1881,16 +1881,16 @@ function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $cal
  * @since 2.7.0
  * @since 5.3.0 Added the `$position` parameter.
  *
- * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string   $menu_title The text to be used for the menu.
- * @param string   $capability The capability required for this menu to be displayed to the user.
- * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $callback   Optional. The function to be called to output the content for this page.
- * @param int      $position   Optional. The position in the menu order this item should appear.
+ * @param string               $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string               $menu_title The text to be used for the menu.
+ * @param string               $capability The capability required for this menu to be displayed to the user.
+ * @param string               $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
+ * @param callable|string|null $callback   Optional. The function to be called to output the content for this page.
+ * @param int                  $position   Optional. The position in the menu order this item should appear.
  * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  *
- * @phpstan-param non-falsy-string  $menu_slug
- * @phpstan-param Optional_Callback $callback
+ * @phpstan-param non-falsy-string     $menu_slug
+ * @phpstan-param WP_Optional_Callback $callback
  */
 function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
diff --git a/src/wp-includes/option.php b/src/wp-includes/option.php
index b25caae0cfe8f..459b666397994 100644
--- a/src/wp-includes/option.php
+++ b/src/wp-includes/option.php
@@ -3120,11 +3120,11 @@ function register_setting( $option_group, $option_name, $args = array() ) {
  * @global array $new_allowed_options
  * @global array $wp_registered_settings
  *
- * @param string   $option_group The settings group name used during registration.
- * @param string   $option_name  The name of the option to unregister.
- * @param callable $deprecated   Optional. Deprecated.
+ * @param string $option_group The settings group name used during registration.
+ * @param string $option_name  The name of the option to unregister.
+ * @param string $deprecated   Optional. Deprecated.
  *
- * @phpstan-param ''|callable $deprecated
+ * @phpstan-param '' $deprecated
  */
 function unregister_setting( $option_group, $option_name, $deprecated = '' ) {
 	global $new_allowed_options, $wp_registered_settings;
diff --git a/tests/phpstan/base.neon b/tests/phpstan/base.neon
index 4960b8bde0420..25cb011c4492a 100644
--- a/tests/phpstan/base.neon
+++ b/tests/phpstan/base.neon
@@ -273,7 +273,7 @@ parameters:
 
 		# An optional callback that is called without arguments, such as an admin page or
 		# custom header callback. Core treats an empty string or null as no callback.
-		Optional_Callback: '''
+		WP_Optional_Callback: '''
 			''|(callable(): mixed)|null
 		'''