From 7fa3597f8aeeca3d9cad7b542e84f2657326de24 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 01/19] Docs: Add refined string types to PHPStan return and
 parameter types.

Adds `non-empty-string`, `non-falsy-string` and `lowercase-string` return types where the function always produces such a string, and narrows a few parameters whose function rejects an empty value: `wp_register_ability()`, `register_post_type()`, `add_shortcode()` and `wp_upload_bits()`.

The map's `non-empty-string` on the `$hook_name` parameter of the hook functions and `non-falsy-string` on `register_rest_route()` are left out, since core itself passes plain strings to them.

See #65817.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VieGtSQtUoVfHiGwTmkvtc
---
 .../includes/class-wp-comments-list-table.php        |  2 ++
 src/wp-admin/includes/media.php                      |  8 ++++++++
 src/wp-admin/includes/ms.php                         |  2 ++
 src/wp-admin/includes/plugin.php                     |  2 ++
 src/wp-admin/includes/template.php                   |  2 ++
 src/wp-admin/includes/widgets.php                    |  2 ++
 src/wp-includes/abilities-api.php                    |  2 ++
 src/wp-includes/block-supports/elements.php          |  2 ++
 src/wp-includes/block-template-utils.php             |  2 ++
 src/wp-includes/blocks.php                           |  4 ++++
 src/wp-includes/class-wp-ajax-response.php           |  2 ++
 src/wp-includes/class-wp-dependencies.php            |  2 ++
 src/wp-includes/class-wp-widget.php                  |  4 ++++
 src/wp-includes/formatting.php                       |  6 ++++++
 src/wp-includes/functions.php                        | 12 ++++++++++++
 src/wp-includes/link-template.php                    |  2 ++
 src/wp-includes/pluggable.php                        |  4 ++++
 src/wp-includes/plugin.php                           |  4 ++++
 src/wp-includes/post.php                             |  2 ++
 src/wp-includes/rewrite.php                          |  2 ++
 src/wp-includes/script-loader.php                    |  2 ++
 src/wp-includes/shortcodes.php                       |  6 ++++++
 22 files changed, 76 insertions(+)

diff --git a/src/wp-admin/includes/class-wp-comments-list-table.php b/src/wp-admin/includes/class-wp-comments-list-table.php
index 2b927a7f81a6a..7294f89d1bd3b 100644
--- a/src/wp-admin/includes/class-wp-comments-list-table.php
+++ b/src/wp-admin/includes/class-wp-comments-list-table.php
@@ -62,6 +62,8 @@ public function __construct( $args = array() ) {
 	 * @param string $name       Comment author name.
 	 * @param int    $comment_id Comment ID.
 	 * @return string Avatar with the user name.
+	 *
+	 * @phpstan-return non-falsy-string
 	 */
 	public function floated_admin_avatar( $name, $comment_id ) {
 		$comment = get_comment( $comment_id );
diff --git a/src/wp-admin/includes/media.php b/src/wp-admin/includes/media.php
index 6134db45b6a95..42de0269a05c2 100644
--- a/src/wp-admin/includes/media.php
+++ b/src/wp-admin/includes/media.php
@@ -1315,6 +1315,8 @@ function image_size_input_fields( $post, $check = '' ) {
  * @param WP_Post $post
  * @param string  $url_type
  * @return string HTML markup for the link URL buttons.
+ *
+ * @phpstan-return non-falsy-string
  */
 function image_link_input_fields( $post, $url_type = '' ) {
 
@@ -1348,6 +1350,8 @@ function image_link_input_fields( $post, $url_type = '' ) {
  *
  * @param WP_Post $edit_post Attachment WP_Post object.
  * @return string HTML markup for the textarea element.
+ *
+ * @phpstan-return non-falsy-string
  */
 function wp_caption_input_textarea( $edit_post ) {
 	// Post data is already escaped.
@@ -1637,6 +1641,8 @@ function get_media_items( $post_id, $errors ) {
  * @param int          $attachment_id Attachment ID for modification.
  * @param string|array $args          Optional. Override defaults.
  * @return string HTML form for attachment.
+ *
+ * @phpstan-return non-falsy-string
  */
 function get_media_item( $attachment_id, $args = null ) {
 	global $redir_tab;
@@ -3013,6 +3019,8 @@ function media_upload_library_form( $errors ) {
  *
  * @param string $default_view
  * @return string HTML content of the form.
+ *
+ * @phpstan-return non-falsy-string
  */
 function wp_media_insert_url_form( $default_view = 'image' ) {
 	/** This filter is documented in wp-admin/includes/media.php */
diff --git a/src/wp-admin/includes/ms.php b/src/wp-admin/includes/ms.php
index 155170aaf4f41..0ae6381ee9855 100644
--- a/src/wp-admin/includes/ms.php
+++ b/src/wp-admin/includes/ms.php
@@ -1211,6 +1211,8 @@ function get_site_screen_help_tab_args() {
  * @since 4.9.0
  *
  * @return string Help sidebar content.
+ *
+ * @phpstan-return non-falsy-string
  */
 function get_site_screen_help_sidebar_content() {
 	return '<p><strong>' . __( 'For more information:' ) . '</strong></p>' .
diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index a34d473bca650..0788e276875fb 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -2146,6 +2146,8 @@ function get_plugin_page_hook( $plugin_page, $parent_page ) {
  * @param string $parent_page The slug name for the parent menu (or the file name of a standard
  *                            WordPress admin page).
  * @return string Hook name for the plugin page.
+ *
+ * @phpstan-return non-falsy-string
  */
 function get_plugin_page_hookname( $plugin_page, $parent_page ) {
 	global $admin_page_hooks;
diff --git a/src/wp-admin/includes/template.php b/src/wp-admin/includes/template.php
index 93428dcc4ae6d..bf57e67952396 100644
--- a/src/wp-admin/includes/template.php
+++ b/src/wp-admin/includes/template.php
@@ -2652,6 +2652,8 @@ function submit_button( $text = '', $type = 'primary', $name = 'submit', $wrap =
  *                                       e.g. `id="search-submit"`, though the array format is generally preferred.
  *                                       Default empty string.
  * @return string Submit button HTML.
+ *
+ * @phpstan-return non-falsy-string
  */
 function get_submit_button( $text = '', $type = 'primary large', $name = 'submit', $wrap = true, $other_attributes = '' ) {
 	if ( ! is_array( $type ) ) {
diff --git a/src/wp-admin/includes/widgets.php b/src/wp-admin/includes/widgets.php
index e751602866b0d..5697a6e9ff0dd 100644
--- a/src/wp-admin/includes/widgets.php
+++ b/src/wp-admin/includes/widgets.php
@@ -322,6 +322,8 @@ function wp_widget_control( $sidebar_args ) {
 /**
  * @param string $classes
  * @return string Modified body classes.
+ *
+ * @phpstan-return non-falsy-string
  */
 function wp_widgets_access_body_class( $classes ) {
 	return "$classes widgets_access ";
diff --git a/src/wp-includes/abilities-api.php b/src/wp-includes/abilities-api.php
index 393e40b56ed8c..66dd394809a23 100644
--- a/src/wp-includes/abilities-api.php
+++ b/src/wp-includes/abilities-api.php
@@ -292,6 +292,8 @@
  *                                                     of ability behavior.
  * }
  * @return WP_Ability|null The registered ability instance on success, `null` on failure.
+ *
+ * @phpstan-param lowercase-string&non-falsy-string $name
  */
 function wp_register_ability( string $name, array $args ): ?WP_Ability {
 	if ( ! doing_action( 'wp_abilities_api_init' ) ) {
diff --git a/src/wp-includes/block-supports/elements.php b/src/wp-includes/block-supports/elements.php
index fe9543a5d5474..e8076cc1bd3ba 100644
--- a/src/wp-includes/block-supports/elements.php
+++ b/src/wp-includes/block-supports/elements.php
@@ -13,6 +13,8 @@
  * @access private
  *
  * @return string The unique class name.
+ *
+ * @phpstan-return lowercase-string&non-falsy-string
  */
 function wp_get_elements_class_name(): string {
 	return wp_unique_prefixed_id( 'wp-elements-' );
diff --git a/src/wp-includes/block-template-utils.php b/src/wp-includes/block-template-utils.php
index 78cd1bbdc15f5..67bfe224d972d 100644
--- a/src/wp-includes/block-template-utils.php
+++ b/src/wp-includes/block-template-utils.php
@@ -1491,6 +1491,8 @@ function wp_is_theme_directory_ignored( $path ) {
  * @since 6.0.0 Adds the whole theme to the export archive.
  *
  * @return WP_Error|string Path of the ZIP file or error on failure.
+ *
+ * @phpstan-return non-falsy-string|WP_Error
  */
 function wp_generate_block_templates_export_file() {
 	$wp_version = wp_get_wp_version();
diff --git a/src/wp-includes/blocks.php b/src/wp-includes/blocks.php
index beaf08d4022c6..e8e137b21108d 100644
--- a/src/wp-includes/blocks.php
+++ b/src/wp-includes/blocks.php
@@ -3084,6 +3084,8 @@ static function ( $format ) {
  * @param WP_Block $block   Block instance.
  * @param bool     $is_next Flag for handling `next/previous` blocks.
  * @return string|null The pagination arrow HTML or null if there is none.
+ *
+ * @phpstan-return non-falsy-string|null
  */
 function get_query_pagination_arrow( $block, $is_next ) {
 	$arrow_map = array(
@@ -3184,6 +3186,8 @@ function build_comment_query_vars_from_block( $block ) {
  * @param string   $pagination_type Optional. Type of the arrow we will be rendering.
  *                                  Accepts 'next' or 'previous'. Default 'next'.
  * @return string|null The pagination arrow HTML or null if there is none.
+ *
+ * @phpstan-return non-falsy-string|null
  */
 function get_comments_pagination_arrow( $block, $pagination_type = 'next' ) {
 	$arrow_map = array(
diff --git a/src/wp-includes/class-wp-ajax-response.php b/src/wp-includes/class-wp-ajax-response.php
index ab747618e0fbf..b9946343ac79f 100644
--- a/src/wp-includes/class-wp-ajax-response.php
+++ b/src/wp-includes/class-wp-ajax-response.php
@@ -63,6 +63,8 @@ public function __construct( $args = '' ) {
 	 *                                             element as CDATA. Default empty array.
 	 * }
 	 * @return string XML response.
+	 *
+	 * @phpstan-return non-falsy-string
 	 */
 	public function add( $args = '' ) {
 		$defaults = array(
diff --git a/src/wp-includes/class-wp-dependencies.php b/src/wp-includes/class-wp-dependencies.php
index 80559201dda03..04d7b849b9ca2 100644
--- a/src/wp-includes/class-wp-dependencies.php
+++ b/src/wp-includes/class-wp-dependencies.php
@@ -539,6 +539,8 @@ public function set_group( $handle, $recursion, $group ) {
 	 *
 	 * @param string[] $load Array of script or style handles to load.
 	 * @return string Etag header.
+	 *
+	 * @phpstan-return non-falsy-string
 	 */
 	public function get_etag( $load ) {
 		/*
diff --git a/src/wp-includes/class-wp-widget.php b/src/wp-includes/class-wp-widget.php
index b131c50db3226..7a1a8ae51d2d9 100644
--- a/src/wp-includes/class-wp-widget.php
+++ b/src/wp-includes/class-wp-widget.php
@@ -213,6 +213,8 @@ public function WP_Widget( $id_base, $name, $widget_options = array(), $control_
 	 *
 	 * @param string $field_name Field name.
 	 * @return string Name attribute for `$field_name`.
+	 *
+	 * @phpstan-return non-falsy-string
 	 */
 	public function get_field_name( $field_name ) {
 		$pos = strpos( $field_name, '[' );
@@ -238,6 +240,8 @@ public function get_field_name( $field_name ) {
 	 *
 	 * @param string $field_name Field name.
 	 * @return string ID attribute for `$field_name`.
+	 *
+	 * @phpstan-return non-falsy-string
 	 */
 	public function get_field_id( $field_name ) {
 		$field_name = str_replace( array( '[]', '[', ']' ), array( '', '-', '' ), $field_name );
diff --git a/src/wp-includes/formatting.php b/src/wp-includes/formatting.php
index c39beaf7b1d68..8fed195da836f 100644
--- a/src/wp-includes/formatting.php
+++ b/src/wp-includes/formatting.php
@@ -622,6 +622,8 @@ function wp_html_split( $input ) {
  * @since 4.4.0
  *
  * @return string The regular expression.
+ *
+ * @phpstan-return non-falsy-string
  */
 function get_html_split_regex() {
 	static $regex;
@@ -2278,6 +2280,8 @@ function sanitize_title_for_query( $title ) {
  *                          When set to 'save', additional entities are converted to hyphens
  *                          or stripped entirely. Default 'display'.
  * @return string The sanitized title.
+ *
+ * @phpstan-return lowercase-string
  */
 function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'display' ) {
 	$title = strip_tags( $title );
@@ -2863,6 +2867,8 @@ function backslashit( $value ) {
  *
  * @param string $value Value to which trailing slash will be added.
  * @return string String with trailing slash added.
+ *
+ * @phpstan-return non-falsy-string
  */
 function trailingslashit( $value ) {
 	return untrailingslashit( $value ) . '/';
diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index 393f50a3aad58..962a91fa7aa41 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -2189,6 +2189,8 @@ function path_is_absolute( $path ) {
  * @param string $base Base path.
  * @param string $path Path relative to $base.
  * @return string The path with the base or absolute path.
+ *
+ * @phpstan-return non-falsy-string
  */
 function path_join( $base, $path ) {
 	if ( path_is_absolute( $path ) ) {
@@ -2955,6 +2957,8 @@ function _wp_check_existing_file_names( $filename, $files ) {
  * }
  * @phpstan-return array{ file: non-empty-string, url: non-empty-string, type: string|false, error: false }
  *                |array{ error: string, ... }
+ *
+ * @phpstan-param non-empty-string $name
  */
 function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {
 	if ( ! empty( $deprecated ) ) {
@@ -4475,6 +4479,8 @@ function _wp_die_process_input( $message, $title = '', $args = array() ) {
  * @param int   $depth Optional. Maximum depth to walk through $value. Must be
  *                     greater than 0. Default 512.
  * @return string|false The JSON encoded string, or false if it cannot be encoded.
+ *
+ * @phpstan-return non-empty-string|false
  */
 function wp_json_encode( $value, $flags = 0, $depth = 512 ) {
 	$json = json_encode( $value, $flags, $depth );
@@ -8172,6 +8178,8 @@ function wp_raise_memory_limit( $context = 'admin' ) {
  * @since 7.0.0 Uses wp_rand if available.
  *
  * @return string UUID.
+ *
+ * @phpstan-return lowercase-string&non-falsy-string
  */
 function wp_generate_uuid4() {
 	static $backup_randomizer = false;
@@ -9206,6 +9214,8 @@ function clean_dirsize_cache( $path ) {
  * @since 6.7.0
  *
  * @return string The current WordPress version.
+ *
+ * @phpstan-return non-falsy-string
  */
 function wp_get_wp_version() {
 	static $wp_version;
@@ -9473,6 +9483,8 @@ function wp_is_heic_image_mime_type( $mime_type ) {
  *
  * @param string $message The message to hash.
  * @return string The hash of the message.
+ *
+ * @phpstan-return non-falsy-string
  */
 function wp_fast_hash(
 	#[\SensitiveParameter]
diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php
index 3d4ffc23b8f62..c92770ae498fa 100644
--- a/src/wp-includes/link-template.php
+++ b/src/wp-includes/link-template.php
@@ -4887,6 +4887,8 @@ function get_the_privacy_policy_link( $before = '', $after = '' ) {
  * @since 6.2.0
  *
  * @return string[] An array of URL hosts.
+ *
+ * @phpstan-return array<lowercase-string>
  */
 function wp_internal_hosts() {
 	static $internal_hosts;
diff --git a/src/wp-includes/pluggable.php b/src/wp-includes/pluggable.php
index 4126f25d7c0fc..d13769cf84afe 100644
--- a/src/wp-includes/pluggable.php
+++ b/src/wp-includes/pluggable.php
@@ -2540,6 +2540,8 @@ function wp_verify_nonce( $nonce, $action = -1 ) {
 	 *
 	 * @param string|int $action Scalar value to add context to the nonce.
 	 * @return string The token.
+	 *
+	 * @phpstan-return lowercase-string&non-falsy-string
 	 */
 	function wp_create_nonce( $action = -1 ) {
 		$user = wp_get_current_user();
@@ -2722,6 +2724,8 @@ function wp_salt( $scheme = 'auth' ) {
 	 * @param string $scheme Authentication scheme (auth, secure_auth, logged_in, nonce).
 	 * @param string $algo   Hashing algorithm to use. Default: 'md5'.
 	 * @return string Hash of $data.
+	 *
+	 * @phpstan-return lowercase-string&non-falsy-string
 	 */
 	function wp_hash( $data, $scheme = 'auth', $algo = 'md5' ) {
 		$salt = wp_salt( $scheme );
diff --git a/src/wp-includes/plugin.php b/src/wp-includes/plugin.php
index a3e9afacdb8dc..7d04b5fb290e5 100644
--- a/src/wp-includes/plugin.php
+++ b/src/wp-includes/plugin.php
@@ -376,6 +376,8 @@ function remove_all_filters( $hook_name, $priority = false ) {
  * @global string[] $wp_current_filter Stores the list of current filters with the current one last
  *
  * @return string|false Hook name of the current filter, false if no filter is running.
+ *
+ * @phpstan-return non-empty-string|false
  */
 function current_filter() {
 	global $wp_current_filter;
@@ -664,6 +666,8 @@ function remove_all_actions( $hook_name, $priority = false ) {
  * @since 3.9.0
  *
  * @return string|false Hook name of the current action, false if no action is running.
+ *
+ * @phpstan-return non-empty-string|false
  */
 function current_action() {
 	return current_filter();
diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php
index 5edc8a50f0299..933c5f874c1bf 100644
--- a/src/wp-includes/post.php
+++ b/src/wp-includes/post.php
@@ -1828,6 +1828,8 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
  * }
  * @return WP_Post_Type|WP_Error The registered post type object on success,
  *                               WP_Error object on failure.
+ *
+ * @phpstan-param lowercase-string&non-empty-string $post_type
  */
 function register_post_type( $post_type, $args = array() ) {
 	global $wp_post_types;
diff --git a/src/wp-includes/rewrite.php b/src/wp-includes/rewrite.php
index 976d2a014b9db..06c4a96507d75 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-return non-falsy-string
  */
 function add_feed( $feedname, $callback ) {
 	global $wp_rewrite;
diff --git a/src/wp-includes/script-loader.php b/src/wp-includes/script-loader.php
index 6b01efa1718ce..6e726ac9163eb 100644
--- a/src/wp-includes/script-loader.php
+++ b/src/wp-includes/script-loader.php
@@ -2939,6 +2939,8 @@ function wp_enqueue_editor_format_library_assets() {
  *
  * @param array<string, string|bool> $attributes Key-value pairs representing `<script>` tag attributes.
  * @return string String containing `<script>` opening and closing tags.
+ *
+ * @phpstan-return non-falsy-string
  */
 function wp_get_script_tag( $attributes ) {
 	/**
diff --git a/src/wp-includes/shortcodes.php b/src/wp-includes/shortcodes.php
index 2727a992fa99d..bd5f74a1ec17b 100644
--- a/src/wp-includes/shortcodes.php
+++ b/src/wp-includes/shortcodes.php
@@ -59,6 +59,8 @@
  *                           including an array of attributes (`$atts`), the shortcode content
  *                           or null if not set (`$content`), and finally the shortcode tag
  *                           itself (`$shortcode_tag`), in that order.
+ *
+ * @phpstan-param non-empty-string $tag
  */
 function add_shortcode( $tag, $callback ) {
 	global $shortcode_tags;
@@ -322,6 +324,8 @@ function _filter_do_shortcode_context() {
  *
  * @param array $tagnames Optional. List of shortcodes to find. Defaults to all registered shortcodes.
  * @return string The shortcode search regular expression.
+ *
+ * @phpstan-return non-falsy-string
  */
 function get_shortcode_regex( $tagnames = null ) {
 	global $shortcode_tags;
@@ -591,6 +595,8 @@ function unescape_invalid_shortcodes( $content ) {
  * @since 4.4.0
  *
  * @return string The shortcode attribute regular expression.
+ *
+ * @phpstan-return non-falsy-string
  */
 function get_shortcode_atts_regex() {
 	return '/([\w-]+)\s*=\s*"([^"]*)"(?:\s|$)|([\w-]+)\s*=\s*\'([^\']*)\'(?:\s|$)|([\w-]+)\s*=\s*([^\s\'"]+)(?:\s|$)|"([^"]*)"(?:\s|$)|\'([^\']*)\'(?:\s|$)|(\S+)(?:\s|$)/';

From 073ece96ab4685cb74fa864fc240f3f1ff1be813 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 5 Oct 2026 15:58:50 +0000
Subject: [PATCH 02/19] Docs: Address review feedback on string types.

Drop the non-empty-string return type from current_filter() and current_action(), since apply_filters() and do_action() do not reject an empty hook name. Use non-falsy-string for register_post_type(), which rejects '0' as well, and place @phpstan-param before @phpstan-return in wp_upload_bits().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015BuoHZQvJMvPEYp4Sfjgvd
---
 src/wp-includes/functions.php | 4 ++--
 src/wp-includes/plugin.php    | 4 ----
 src/wp-includes/post.php      | 2 +-
 3 files changed, 3 insertions(+), 7 deletions(-)

diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index 962a91fa7aa41..60c3ecb26943d 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -2955,10 +2955,10 @@ function _wp_check_existing_file_names( $filename, $files ) {
  *                               Not set if there has been an error.
  *     @type string|false $error Error message, if there has been an error.
  * }
- * @phpstan-return array{ file: non-empty-string, url: non-empty-string, type: string|false, error: false }
- *                |array{ error: string, ... }
  *
  * @phpstan-param non-empty-string $name
+ * @phpstan-return array{ file: non-empty-string, url: non-empty-string, type: string|false, error: false }
+ *                |array{ error: string, ... }
  */
 function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {
 	if ( ! empty( $deprecated ) ) {
diff --git a/src/wp-includes/plugin.php b/src/wp-includes/plugin.php
index 7d04b5fb290e5..a3e9afacdb8dc 100644
--- a/src/wp-includes/plugin.php
+++ b/src/wp-includes/plugin.php
@@ -376,8 +376,6 @@ function remove_all_filters( $hook_name, $priority = false ) {
  * @global string[] $wp_current_filter Stores the list of current filters with the current one last
  *
  * @return string|false Hook name of the current filter, false if no filter is running.
- *
- * @phpstan-return non-empty-string|false
  */
 function current_filter() {
 	global $wp_current_filter;
@@ -666,8 +664,6 @@ function remove_all_actions( $hook_name, $priority = false ) {
  * @since 3.9.0
  *
  * @return string|false Hook name of the current action, false if no action is running.
- *
- * @phpstan-return non-empty-string|false
  */
 function current_action() {
 	return current_filter();
diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php
index 933c5f874c1bf..d027537c69247 100644
--- a/src/wp-includes/post.php
+++ b/src/wp-includes/post.php
@@ -1829,7 +1829,7 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
  * @return WP_Post_Type|WP_Error The registered post type object on success,
  *                               WP_Error object on failure.
  *
- * @phpstan-param lowercase-string&non-empty-string $post_type
+ * @phpstan-param lowercase-string&non-falsy-string $post_type
  */
 function register_post_type( $post_type, $args = array() ) {
 	global $wp_post_types;

From 31fa5b2ce5e9de6020209ec1ed76ac270558986e Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 11:47:38 -0700
Subject: [PATCH 03/19] Assert the type of `$wp_version` in
 `wp_get_wp_version()`.

PHPStan cannot see that requiring `version.php` assigns the static
`$wp_version`, so the return value was inferred as `mixed`, which
conflicts with the `non-falsy-string` return type. An inline `@var`
after the `require` asserts the type. A `@global` tag would not work,
since the function deliberately avoids the global.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/functions.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index a205ef31f52d2..f170526b664b9 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -9229,6 +9229,7 @@ function wp_get_wp_version() {
 		require ABSPATH . WPINC . '/version.php';
 	}
 
+	/** @var non-falsy-string $wp_version */
 	return $wp_version;
 }
 

From 8290702614289ee73cf5d34f4b27438f45bb8d68 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 11:48:32 -0700
Subject: [PATCH 04/19] Type the static `$regex` in `get_html_split_regex()`.

The untyped static was inferred as `mixed`, which conflicts with the
`non-falsy-string` return type. Annotating it as
`non-falsy-string|null` lets PHPStan narrow it to `non-falsy-string`
by the time it is returned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/formatting.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/wp-includes/formatting.php b/src/wp-includes/formatting.php
index ab6c0aca3e353..12b2e7049c8d8 100644
--- a/src/wp-includes/formatting.php
+++ b/src/wp-includes/formatting.php
@@ -626,6 +626,7 @@ function wp_html_split( $input ) {
  * @phpstan-return non-falsy-string
  */
 function get_html_split_regex() {
+	/** @var non-falsy-string|null $regex */
 	static $regex;
 
 	if ( ! isset( $regex ) ) {

From 5a8cf6b5cf68ed8f44601ec3f5e092a53a23328f Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 11:50:02 -0700
Subject: [PATCH 05/19] Assert the lowercase return type of
 `sanitize_title_with_dashes()`.

PHPStan loses the `lowercase-string` type established by `strtolower()`
once the title passes through `str_replace()` and `preg_replace()`, so
the return value was inferred as `string`. At runtime only lowercase
characters can remain after the `[^%a-z0-9 _-]` replacement, so an
inline `@var` asserts the declared return type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/formatting.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/wp-includes/formatting.php b/src/wp-includes/formatting.php
index 12b2e7049c8d8..07f2b4188de93 100644
--- a/src/wp-includes/formatting.php
+++ b/src/wp-includes/formatting.php
@@ -2402,6 +2402,7 @@ function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'displa
 	$title = preg_replace( '|-+|', '-', $title );
 	$title = trim( $title, '-' );
 
+	/** @var lowercase-string $title Only lowercase characters remain after the replacements above. */
 	return $title;
 }
 

From 4ccdf6ad4847ee1461afc12474612c47cb7391d5 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 11:58:49 -0700
Subject: [PATCH 06/19] Return a list of lowercase hosts from
 `wp_internal_hosts()`.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The untyped static `$internal_hosts` was inferred as `mixed`, which
conflicts with the declared return type. Annotating the static fixes
that, since `array_map( 'strtolower', … )` already yields lowercase
strings.

The result of `array_unique()` is also passed through `array_values()`,
so that the function returns a `list` even when a filter adds a
duplicate host. Callers only check membership with `in_array()`, so
the reindexing does not affect them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/link-template.php | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php
index 9cda6da9a3d37..a35203c65e996 100644
--- a/src/wp-includes/link-template.php
+++ b/src/wp-includes/link-template.php
@@ -4899,9 +4899,10 @@ function get_the_privacy_policy_link( $before = '', $after = '' ) {
  *
  * @return string[] An array of URL hosts.
  *
- * @phpstan-return array<lowercase-string>
+ * @phpstan-return list<lowercase-string>
  */
 function wp_internal_hosts() {
+	/** @var list<lowercase-string>|null $internal_hosts */
 	static $internal_hosts;
 
 	if ( empty( $internal_hosts ) ) {
@@ -4918,8 +4919,10 @@ function wp_internal_hosts() {
 				wp_parse_url( home_url(), PHP_URL_HOST ),
 			)
 		);
-		$internal_hosts = array_unique(
-			array_map( 'strtolower', (array) $internal_hosts )
+		$internal_hosts = array_values(
+			array_unique(
+				array_map( 'strtolower', (array) $internal_hosts )
+			)
 		);
 	}
 

From 172abeb02a823c1cf5a747e61bce9eb339c2783c Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:00:19 -0700
Subject: [PATCH 07/19] Assert the lowercase return type of
 `wp_generate_uuid4()`.

PHPStan infers `non-falsy-string` from the `sprintf()` format, but does
not know that the `%x` conversion only produces lowercase hex digits.
The result is now assigned to a variable with an inline `@var`, so
that it matches the declared `lowercase-string&non-falsy-string` return
type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/functions.php | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index f170526b664b9..e3655b00adb36 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -8200,7 +8200,8 @@ function wp_generate_uuid4() {
 		$randomizer = $backup_randomizer;
 	}
 
-	return sprintf(
+	/** @var lowercase-string&non-falsy-string $uuid The %x conversion only produces lowercase hex digits. */
+	$uuid = sprintf(
 		'%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
 		$randomizer( 0, 0xffff ),
 		$randomizer( 0, 0xffff ),
@@ -8211,6 +8212,8 @@ function wp_generate_uuid4() {
 		$randomizer( 0, 0xffff ),
 		$randomizer( 0, 0xffff )
 	);
+
+	return $uuid;
 }
 
 /**

From b96940814aafdb5144b97d62ba840814f113a63a Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:05:46 -0700
Subject: [PATCH 08/19] Assert a non-falsy path when `path_is_absolute()`
 returns true.

The conditional return type of `path_is_absolute()` narrows its result
but not its argument, so the early `return $path;` in `path_join()` was
inferred as `string`, which conflicts with its `non-falsy-string` return
type. Every path that returns true requires a path that is neither empty
nor `'0'`, so `@phpstan-assert-if-true` narrows `$path` accordingly. The
false branch is left unnarrowed, since relative paths like `'../'` also
return false.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/functions.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index e3655b00adb36..114a9484f5659 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -2150,6 +2150,7 @@ function wp_mkdir_p( $target ) {
  * @return bool True if path is absolute, false is not absolute.
  *
  * @phpstan-return ( $path is non-falsy-string ? bool : false )
+ * @phpstan-assert-if-true non-falsy-string $path
  */
 function path_is_absolute( $path ) {
 	/*

From c7ab136417c48fb7b516338131575afb2f11def7 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:18:42 -0700
Subject: [PATCH 09/19] Narrow the taxonomy key type for `register_taxonomy()`.

The key is documented as only containing lowercase alphanumeric
characters, dashes, and underscores, and the function rejects empty
names. This matches the type the branch gives `register_post_type()`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/taxonomy.php | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php
index 1159ca64e6d2d..ea13e99271cf0 100644
--- a/src/wp-includes/taxonomy.php
+++ b/src/wp-includes/taxonomy.php
@@ -518,6 +518,8 @@ function is_taxonomy_hierarchical( $taxonomy ) {
  *                                                Default false.
  * }
  * @return WP_Taxonomy|WP_Error The registered taxonomy object on success, WP_Error object on failure.
+ *
+ * @phpstan-param lowercase-string&non-falsy-string $taxonomy
  */
 function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
 	global $wp_taxonomies;

From f4474a9ec2f71aef5f1b2c9d6ebed6c329d9856d Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:18:53 -0700
Subject: [PATCH 10/19] Narrow the post status name type for
 `register_post_status()`.

The name is passed through `sanitize_key()`, so the registered status
is always lowercase, and every core call registers a lowercase literal.
This matches the type the branch gives `register_post_type()`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/post.php | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php
index bf21e275dece3..528eab564272b 100644
--- a/src/wp-includes/post.php
+++ b/src/wp-includes/post.php
@@ -1453,6 +1453,8 @@ function _wp_privacy_statuses() {
  *                                                  Default to false.
  * }
  * @return object
+ *
+ * @phpstan-param lowercase-string&non-falsy-string $post_status
  */
 function register_post_status( $post_status, $args = array() ) {
 	global $wp_post_statuses;

From cba30d822e4ca1b4898322f0f73f92a61110bf83 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:19:05 -0700
Subject: [PATCH 11/19] Narrow the ability and ability category name types.

`WP_Abilities_Registry::register()` validates the name against
`/^[a-z0-9-]+\/[a-z0-9-]+$/`, so it now has the same
`lowercase-string&non-falsy-string` type as `wp_register_ability()`.

`wp_register_ability_category()` and
`WP_Ability_Categories_Registry::register()` validate the slug against
`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`. That pattern accepts `'0'`, so the slug
is narrowed to `lowercase-string&non-empty-string`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/abilities-api.php                               | 2 ++
 src/wp-includes/abilities-api/class-wp-abilities-registry.php   | 2 ++
 .../abilities-api/class-wp-ability-categories-registry.php      | 2 ++
 3 files changed, 6 insertions(+)

diff --git a/src/wp-includes/abilities-api.php b/src/wp-includes/abilities-api.php
index 66dd394809a23..abd3684273a5a 100644
--- a/src/wp-includes/abilities-api.php
+++ b/src/wp-includes/abilities-api.php
@@ -654,6 +654,8 @@ function _wp_get_abilities_match_meta( array $meta, array $conditions ): bool {
  *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
  * }
  * @return WP_Ability_Category|null The registered ability category instance on success, `null` on failure.
+ *
+ * @phpstan-param lowercase-string&non-empty-string $slug
  */
 function wp_register_ability_category( string $slug, array $args ): ?WP_Ability_Category {
 	if ( ! doing_action( 'wp_abilities_api_categories_init' ) ) {
diff --git a/src/wp-includes/abilities-api/class-wp-abilities-registry.php b/src/wp-includes/abilities-api/class-wp-abilities-registry.php
index 813c3dd49f7be..90a2349a89ce1 100644
--- a/src/wp-includes/abilities-api/class-wp-abilities-registry.php
+++ b/src/wp-includes/abilities-api/class-wp-abilities-registry.php
@@ -84,6 +84,8 @@ final class WP_Abilities_Registry {
 	 *     @type string               $ability_class         Optional. Custom class to instantiate instead of WP_Ability.
 	 * }
 	 * @return WP_Ability|null The registered ability instance on success, null on failure.
+	 *
+	 * @phpstan-param lowercase-string&non-falsy-string $name
 	 */
 	public function register( string $name, array $args ): ?WP_Ability {
 		if ( ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $name ) ) {
diff --git a/src/wp-includes/abilities-api/class-wp-ability-categories-registry.php b/src/wp-includes/abilities-api/class-wp-ability-categories-registry.php
index 58bc4323ced69..92e6dbdd84f65 100644
--- a/src/wp-includes/abilities-api/class-wp-ability-categories-registry.php
+++ b/src/wp-includes/abilities-api/class-wp-ability-categories-registry.php
@@ -53,6 +53,8 @@ final class WP_Ability_Categories_Registry {
 	 *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
 	 * }
 	 * @return WP_Ability_Category|null The registered ability category instance on success, null on failure.
+	 *
+	 * @phpstan-param lowercase-string&non-empty-string $slug
 	 */
 	public function register( string $slug, array $args ): ?WP_Ability_Category {
 		if ( $this->is_registered( $slug ) ) {

From c8cd212824a78513ba409298b2cedeee4546e28d Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:19:19 -0700
Subject: [PATCH 12/19] Narrow the block bindings source name type.

`WP_Block_Bindings_Registry::register()` rejects uppercase characters
and requires a name matching `/^[a-z0-9-]+\/[a-z0-9-]+$/`, so it and
`register_block_bindings_source()` now take a
`lowercase-string&non-falsy-string`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/block-bindings.php                   | 2 ++
 src/wp-includes/class-wp-block-bindings-registry.php | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/src/wp-includes/block-bindings.php b/src/wp-includes/block-bindings.php
index e3425c1538a7c..1250f92e99848 100644
--- a/src/wp-includes/block-bindings.php
+++ b/src/wp-includes/block-bindings.php
@@ -90,6 +90,8 @@
  *     @type string[] $uses_context       Optional. Array of values to add to block `uses_context` needed by the source.
  * }
  * @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure.
+ *
+ * @phpstan-param lowercase-string&non-falsy-string $source_name
  */
 function register_block_bindings_source( string $source_name, array $source_properties ) {
 	return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties );
diff --git a/src/wp-includes/class-wp-block-bindings-registry.php b/src/wp-includes/class-wp-block-bindings-registry.php
index f4591656e7101..b20f0a692cd76 100644
--- a/src/wp-includes/class-wp-block-bindings-registry.php
+++ b/src/wp-includes/class-wp-block-bindings-registry.php
@@ -80,6 +80,8 @@ final class WP_Block_Bindings_Registry {
 	 *     @type string[] $uses_context       Optional. Array of values to add to block `uses_context` needed by the source.
 	 * }
 	 * @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure.
+	 *
+	 * @phpstan-param lowercase-string&non-falsy-string $source_name
 	 */
 	public function register( string $source_name, array $source_properties ) {
 		if ( ! is_string( $source_name ) ) {

From a51d0e1561fb1648de2724895232bb209c5ceaa8 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:21:07 -0700
Subject: [PATCH 13/19] Narrow the icon and icon collection name types.

`WP_Icon_Collections_Registry::register()` validates the slug against
`/^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$/`. That pattern accepts `'0'`, so the
slug is narrowed to `lowercase-string&non-empty-string`.

`WP_Icons_Registry::register()` requires a namespaced name whose
collection is registered and whose icon name is lowercase, so the name
is narrowed to `lowercase-string&non-falsy-string`.

The wrapper functions get the same types. To keep the default icons
registered by `_wp_register_default_icons()` consistent with this, the
generated icon manifest is given an array shape with lowercase icon
names and collection slugs. This also resolves the `mixed` errors
previously reported for the manifest's label, collections, and keywords.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../class-wp-icon-collections-registry.php           |  2 ++
 src/wp-includes/class-wp-icons-registry.php          |  2 ++
 src/wp-includes/icons.php                            | 12 ++++++++++++
 3 files changed, 16 insertions(+)

diff --git a/src/wp-includes/class-wp-icon-collections-registry.php b/src/wp-includes/class-wp-icon-collections-registry.php
index dcfe8422851b8..e7e19d02b19e0 100644
--- a/src/wp-includes/class-wp-icon-collections-registry.php
+++ b/src/wp-includes/class-wp-icon-collections-registry.php
@@ -51,6 +51,8 @@ class WP_Icon_Collections_Registry {
 	 *                               via {@see wp_get_icon()}. Default true.
 	 * }
 	 * @return bool True if the collection was registered successfully, false otherwise.
+	 *
+	 * @phpstan-param lowercase-string&non-empty-string $collection_slug
 	 */
 	public function register( $collection_slug, $collection_properties ) {
 		if ( ! isset( $collection_slug ) || ! is_string( $collection_slug ) ) {
diff --git a/src/wp-includes/class-wp-icons-registry.php b/src/wp-includes/class-wp-icons-registry.php
index 361506a67ef91..6186a0b48907a 100644
--- a/src/wp-includes/class-wp-icons-registry.php
+++ b/src/wp-includes/class-wp-icons-registry.php
@@ -62,6 +62,8 @@ protected function __construct() {}
 	 *                               `get_registered_icons()` alongside the name and label.
 	 * }
 	 * @return bool True if the icon was registered with success and false otherwise.
+	 *
+	 * @phpstan-param lowercase-string&non-falsy-string $icon_name
 	 */
 	public function register( $icon_name, $icon_properties ) {
 		if ( ! isset( $icon_name ) || ! is_string( $icon_name ) ) {
diff --git a/src/wp-includes/icons.php b/src/wp-includes/icons.php
index 05588c3cf4ea9..156592e8d6012 100644
--- a/src/wp-includes/icons.php
+++ b/src/wp-includes/icons.php
@@ -25,6 +25,8 @@
  *                               via {@see wp_get_icon()}. Default true.
  * }
  * @return bool True if the icon collection was registered successfully, else false.
+ *
+ * @phpstan-param lowercase-string&non-empty-string $slug
  */
 function wp_register_icon_collection( $slug, $args ) {
 	return WP_Icon_Collections_Registry::get_instance()->register( $slug, $args );
@@ -65,6 +67,8 @@ function wp_unregister_icon_collection( $slug ) {
  *                               `get_registered_icons()` alongside the name and label.
  * }
  * @return bool True if the icon was registered successfully, else false.
+ *
+ * @phpstan-param lowercase-string&non-falsy-string $icon_name
  */
 function wp_register_icon( $icon_name, $args ) {
 	return WP_Icons_Registry::get_instance()->register( $icon_name, $args );
@@ -125,6 +129,14 @@ function _wp_register_default_icons() {
 		return;
 	}
 
+	/**
+	 * @var array<lowercase-string&non-falsy-string, array{
+	 *     label: string,
+	 *     filePath: non-empty-string,
+	 *     collections: non-empty-list<lowercase-string&non-falsy-string>,
+	 *     keywords?: list<string>
+	 * }> $collection
+	 */
 	$collection = include $manifest_path;
 
 	if ( empty( $collection ) ) {

From 660115fc7d8599f2c20c7f972c2cc52b0200c9de Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:21:17 -0700
Subject: [PATCH 14/19] Narrow the connector ID type.

`WP_Connector_Registry::register()` validates the ID against
`/^[a-z0-9_-]+$/`. That pattern accepts `'0'`, so the ID is narrowed to
`lowercase-string&non-empty-string`.

The default AI providers are registered with IDs that come from the
AI Client, which PHPStan cannot see are lowercase. `ProviderMetadata`
already rejects IDs that are not lowercase, so an inline `@var` asserts
the type at that call site.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/class-wp-connector-registry.php | 1 +
 src/wp-includes/connectors.php                  | 1 +
 2 files changed, 2 insertions(+)

diff --git a/src/wp-includes/class-wp-connector-registry.php b/src/wp-includes/class-wp-connector-registry.php
index eed6e2654a65e..70b967e8ab517 100644
--- a/src/wp-includes/class-wp-connector-registry.php
+++ b/src/wp-includes/class-wp-connector-registry.php
@@ -127,6 +127,7 @@ final class WP_Connector_Registry {
 	 * }
 	 * @return array|null The registered connector data on success, null on failure.
 	 *
+	 * @phpstan-param lowercase-string&non-empty-string $id
 	 * @phpstan-param array{
 	 *     name: non-empty-string,
 	 *     description?: string,
diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php
index 9aed5f1f4d7aa..9c83a973eba43 100644
--- a/src/wp-includes/connectors.php
+++ b/src/wp-includes/connectors.php
@@ -384,6 +384,7 @@ function _wp_connectors_register_default_ai_providers( WP_Connector_Registry $re
 	}
 
 	// Register all default connectors directly on the registry.
+	/** @var lowercase-string&non-empty-string $id AI Client provider IDs are validated as lowercase by ProviderMetadata. */
 	foreach ( $defaults as $id => $args ) {
 		if ( 'api_key' === $args['authentication']['method'] ) {
 			$sanitized_id = str_replace( '-', '_', $id );

From b36cc6ea9023a17e788eb082b3f0ae67e826e0fd Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:33:38 -0700
Subject: [PATCH 15/19] Narrow the block type name type in the block type
 registry.

`WP_Block_Type_Registry::register()` rejects uppercase characters and
requires a name matching `/^[a-z0-9-]+\/[a-z0-9-]+$/`, so a string name
is narrowed to `lowercase-string&non-falsy-string`.

`register_block_type()` keeps a plain `string` parameter, since it also
accepts a path to block metadata. Once the path case has returned, the
remaining string should be a block type name, which an inline `@var`
asserts before it is passed to the registry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/blocks.php                       | 1 +
 src/wp-includes/class-wp-block-type-registry.php | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/src/wp-includes/blocks.php b/src/wp-includes/blocks.php
index e8e137b21108d..1701548d8d3fa 100644
--- a/src/wp-includes/blocks.php
+++ b/src/wp-includes/blocks.php
@@ -843,6 +843,7 @@ function register_block_type( $block_type, $args = array() ) {
 		return register_block_type_from_metadata( $block_type, $args );
 	}
 
+	/** @var (lowercase-string&non-falsy-string)|WP_Block_Type $block_type A string that is not a path to block metadata should be a block type name. */
 	return WP_Block_Type_Registry::get_instance()->register( $block_type, $args );
 }
 
diff --git a/src/wp-includes/class-wp-block-type-registry.php b/src/wp-includes/class-wp-block-type-registry.php
index 93a8615b52a96..d3fe35d15f901 100644
--- a/src/wp-includes/class-wp-block-type-registry.php
+++ b/src/wp-includes/class-wp-block-type-registry.php
@@ -44,6 +44,8 @@ final class WP_Block_Type_Registry {
 	 *                                   of `WP_Block_Type`. See WP_Block_Type::__construct() for information
 	 *                                   on accepted arguments. Default empty array.
 	 * @return WP_Block_Type|false The registered block type on success, or false on failure.
+	 *
+	 * @phpstan-param (lowercase-string&non-falsy-string)|WP_Block_Type $name
 	 */
 	public function register( $name, $args = array() ) {
 		$block_type = null;

From b21d89edde81d06a8a9f8a68af105e9991d3f3ea Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:33:50 -0700
Subject: [PATCH 16/19] Narrow the block template name type.

`WP_Block_Templates_Registry::register()` rejects uppercase characters
and requires a name matching `/^[a-z0-9_\-]+\/\/[a-z0-9_\-]+$/`, so it
and `register_block_template()` now take a
`lowercase-string&non-falsy-string`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/block-template.php                    | 2 ++
 src/wp-includes/class-wp-block-templates-registry.php | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/src/wp-includes/block-template.php b/src/wp-includes/block-template.php
index 8c34b05d016ae..3f24933dfcf59 100644
--- a/src/wp-includes/block-template.php
+++ b/src/wp-includes/block-template.php
@@ -501,6 +501,8 @@ function _resolve_template_for_new_post( $wp_query ) {
  *     @type string        $plugin                Optional. Slug of the plugin that registers the template.
  * }
  * @return WP_Block_Template|WP_Error The registered template object on success, WP_Error object on failure.
+ *
+ * @phpstan-param lowercase-string&non-falsy-string $template_name
  */
 function register_block_template( $template_name, $args = array() ) {
 	return WP_Block_Templates_Registry::get_instance()->register( $template_name, $args );
diff --git a/src/wp-includes/class-wp-block-templates-registry.php b/src/wp-includes/class-wp-block-templates-registry.php
index 6d47158cf8c32..fa1c180988844 100644
--- a/src/wp-includes/class-wp-block-templates-registry.php
+++ b/src/wp-includes/class-wp-block-templates-registry.php
@@ -36,6 +36,8 @@ final class WP_Block_Templates_Registry {
 	 * @param string $template_name Template name including namespace.
 	 * @param array  $args          Optional. Array of template arguments.
 	 * @return WP_Block_Template|WP_Error The registered template on success, or WP_Error on failure.
+	 *
+	 * @phpstan-param lowercase-string&non-falsy-string $template_name
 	 */
 	public function register( $template_name, $args = array() ) {
 

From 4eb2a8d5ee3c9f5e569b863b3b35f6517c69063e Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:33:59 -0700
Subject: [PATCH 17/19] Narrow the menu slug type for admin menu page
 functions.

`add_menu_page()`, `add_submenu_page()`, and the `add_*_page()` helpers
now take a `non-falsy-string` menu slug. The slug is not narrowed to
lowercase, even though the documentation says it should be: established
plugins register mixed-case slugs that appear in admin URLs, so they
cannot be changed without breaking existing links.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-admin/includes/plugin.php | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index 918fb5d7946af..c627e6d8f55d5 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -1399,6 +1399,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 non-falsy-string $menu_slug
  */
 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;
@@ -1494,6 +1496,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 non-falsy-string $menu_slug
  */
 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,
@@ -1607,6 +1611,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 non-falsy-string $menu_slug
  */
 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 );
@@ -1631,6 +1637,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 non-falsy-string $menu_slug
  */
 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 );
@@ -1655,6 +1663,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 non-falsy-string $menu_slug
  */
 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 );
@@ -1679,6 +1689,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 non-falsy-string $menu_slug
  */
 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 );
@@ -1703,6 +1715,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 non-falsy-string $menu_slug
  */
 function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	if ( current_user_can( 'edit_users' ) ) {
@@ -1732,6 +1746,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 non-falsy-string $menu_slug
  */
 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 );
@@ -1756,6 +1772,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 non-falsy-string $menu_slug
  */
 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 );
@@ -1780,6 +1798,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 non-falsy-string $menu_slug
  */
 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 );
@@ -1804,6 +1824,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 non-falsy-string $menu_slug
  */
 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 );
@@ -1828,6 +1850,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 non-falsy-string $menu_slug
  */
 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 );
@@ -1852,6 +1876,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 non-falsy-string $menu_slug
  */
 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 1b05091176c044e13fb239813068e7c0e3e17086 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:40:36 -0700
Subject: [PATCH 18/19] Use `@phpstan-var` for the icon manifest array shape.

The shape uses PHPStan-only types such as `lowercase-string` and
`non-empty-list`, so it belongs in a `@phpstan-` prefixed tag, where
other tools that read docblocks will not misinterpret it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/icons.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/wp-includes/icons.php b/src/wp-includes/icons.php
index 156592e8d6012..14b19f0309090 100644
--- a/src/wp-includes/icons.php
+++ b/src/wp-includes/icons.php
@@ -130,7 +130,7 @@ function _wp_register_default_icons() {
 	}
 
 	/**
-	 * @var array<lowercase-string&non-falsy-string, array{
+	 * @phpstan-var array<lowercase-string&non-falsy-string, array{
 	 *     label: string,
 	 *     filePath: non-empty-string,
 	 *     collections: non-empty-list<lowercase-string&non-falsy-string>,

From a88ab20010ae828ec7766eee660222e944cc8851 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 7 Oct 2026 12:46:20 -0700
Subject: [PATCH 19/19] Use `@var` again for the icon manifest array shape.

This reverts the switch to `@phpstan-var`. Inline annotations on local
variables are not part of the developer documentation, and core already
uses plain `@var` with array shapes for them, as in `blocks.php`. The
`@phpstan-` prefix is only needed in docblocks that document a symbol.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/wp-includes/icons.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/wp-includes/icons.php b/src/wp-includes/icons.php
index 14b19f0309090..156592e8d6012 100644
--- a/src/wp-includes/icons.php
+++ b/src/wp-includes/icons.php
@@ -130,7 +130,7 @@ function _wp_register_default_icons() {
 	}
 
 	/**
-	 * @phpstan-var array<lowercase-string&non-falsy-string, array{
+	 * @var array<lowercase-string&non-falsy-string, array{
 	 *     label: string,
 	 *     filePath: non-empty-string,
 	 *     collections: non-empty-list<lowercase-string&non-falsy-string>,