From 64b91ee739884f43f89c57fbeefabe1b19c3f292 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:05:53 -0700
Subject: [PATCH 01/18] Add a conditional return type to
 `WP_Comment_Query::query()`.

The `get_comments()` function already declares a conditional `@phpstan-return`
that narrows to `non-negative-int` for `count`, to `non-negative-int[]` for
`fields => 'ids'`, and to `array<int, WP_Comment>` otherwise. That function is a
thin wrapper that immediately delegates to `WP_Comment_Query::query()`, which
declared only the unnarrowed union, so the narrowing was asserted at the wrapper
rather than derived from the method that actually produces the value.

Declare the same condition on `WP_Comment_Query::query()`. Callers of the method
now get the same narrowing the function's callers already had, and the
function's own conditional type follows from its return statement instead of
standing on its own.

`WP_Comment_Query::get_comments()` keeps the plain union. A PHPStan conditional
return type can only branch on a parameter or a template type, and that method
takes no parameters -- its behavior depends on `$this->query_vars`, which the
PHPDoc type grammar cannot express.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/class-wp-comment-query.php | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/wp-includes/class-wp-comment-query.php b/src/wp-includes/class-wp-comment-query.php
index f80864d31c8bc..a82cd5cd22372 100644
--- a/src/wp-includes/class-wp-comment-query.php
+++ b/src/wp-includes/class-wp-comment-query.php
@@ -365,7 +365,12 @@ public function parse_query( $query = '' ) {
 	 *
 	 * @param string|array $query Array or URL query string of parameters.
 	 * @return WP_Comment[]|int[]|int List of comments, or number of comments when 'count' is passed as a query var.
-	 * @phpstan-return array<int, WP_Comment>|non-negative-int[]|non-negative-int
+	 *
+	 * @phpstan-return (
+	 *     $query is array{ count: true, ... } ? non-negative-int : (
+	 *         $query is array{ fields: 'ids', ... } ? non-negative-int[] : array<int, WP_Comment>
+	 *     )
+	 * )
 	 */
 	public function query( $query ) {
 		$this->query_vars = wp_parse_args( $query );

From 489bb4d3df3c1d393946db8968011e4be11176ef Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:06:18 -0700
Subject: [PATCH 02/18] Add conditional return types for the `$output`
 parameter of term and category getters.

`get_post()` and `get_comment()` already declare a conditional `@phpstan-return`
that resolves `$output` to the concrete shape it selects: an associative array
for `ARRAY_A`, a list for `ARRAY_N`, and the object otherwise. The term and
category getters take the same `$output` parameter but declared only the
unnarrowed union, so every caller had to re-establish the type by hand.

Declare the condition on `get_term()`, `get_term_by()`, `get_category()`,
`get_category_by_path()`, and `get_tag()`, along with the
`'OBJECT'|'ARRAY_A'|'ARRAY_N'` parameter type the condition branches on. The
error union each function can return regardless of `$output` -- `WP_Error` and
`null`, or `false` for `get_term_by()` -- is repeated in every branch, since
those early returns happen before `$output` is consulted.

Give `WP_Term::to_array()` the `array<string, mixed>` value type that
`WP_Post::to_array()` and `WP_Comment::to_array()` already have. Without it the
`ARRAY_A` and `ARRAY_N` branches degrade to an untyped array and the narrowing
is lost at the point it matters most.

Across the full tree this removes 53 static-analysis errors and introduces none.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/category.php                  | 21 +++++++++++++++++++
 src/wp-includes/class-wp-term.php             |  2 +-
 src/wp-includes/taxonomy.php                  | 14 +++++++++++++
 tests/phpstan/baselines/isset.property.neon   |  2 +-
 .../phpstan/baselines/property.nonObject.neon | 15 -------------
 .../phpstan/baselines/property.notFound.neon  |  5 +++++
 6 files changed, 42 insertions(+), 17 deletions(-)

diff --git a/src/wp-includes/category.php b/src/wp-includes/category.php
index dbb48d630b076..37f41855c1b45 100644
--- a/src/wp-includes/category.php
+++ b/src/wp-includes/category.php
@@ -88,6 +88,13 @@ function get_categories( $args = '' ) {
  * @return WP_Term|array|WP_Error|null Category data in type defined by $output parameter.
  *                                     Returns a WP_Term object with backwards compatible property aliases filled in.
  *                                     WP_Error if $category is empty, null if it does not exist.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? array<string, mixed>|WP_Error|null : (
+ *         $output is 'ARRAY_N' ? list<mixed>|WP_Error|null : WP_Term|WP_Error|null
+ *     )
+ * )
  */
 function get_category( $category, $output = OBJECT, $filter = 'raw' ) {
 	$category = get_term( $category, 'category', $output, $filter );
@@ -121,6 +128,13 @@ function get_category( $category, $output = OBJECT, $filter = 'raw' ) {
  *                              correspond to a WP_Term object, an associative array, or a numeric array,
  *                              respectively. Default OBJECT.
  * @return WP_Term|array|WP_Error|null Type is based on $output value.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? array<string, mixed>|WP_Error|null : (
+ *         $output is 'ARRAY_N' ? list<mixed>|WP_Error|null : WP_Term|WP_Error|null
+ *     )
+ * )
  */
 function get_category_by_path( $category_path, $full_match = true, $output = OBJECT ) {
 	$category_path  = rawurlencode( urldecode( $category_path ) );
@@ -339,6 +353,13 @@ function get_tags( $args = '' ) {
  * @param string             $filter Optional. How to sanitize tag fields. Default 'raw'.
  * @return WP_Term|array|WP_Error|null Tag data in type defined by $output parameter.
  *                                     WP_Error if $tag is empty, null if it does not exist.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? array<string, mixed>|WP_Error|null : (
+ *         $output is 'ARRAY_N' ? list<mixed>|WP_Error|null : WP_Term|WP_Error|null
+ *     )
+ * )
  */
 function get_tag( $tag, $output = OBJECT, $filter = 'raw' ) {
 	return get_term( $tag, 'post_tag', $output, $filter );
diff --git a/src/wp-includes/class-wp-term.php b/src/wp-includes/class-wp-term.php
index 33547e4cbef98..a9a58da875e4a 100644
--- a/src/wp-includes/class-wp-term.php
+++ b/src/wp-includes/class-wp-term.php
@@ -225,7 +225,7 @@ public function filter( $filter ) {
 	 *
 	 * @since 4.4.0
 	 *
-	 * @return array Object as array.
+	 * @return array<string, mixed> Object as array.
 	 */
 	public function to_array() {
 		return get_object_vars( $this );
diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php
index d13a11e65581c..52e6b99b7b802 100644
--- a/src/wp-includes/taxonomy.php
+++ b/src/wp-includes/taxonomy.php
@@ -979,6 +979,13 @@ function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
  * @param string             $filter   Optional. How to sanitize term fields. Default 'raw'.
  * @return WP_Term|array|WP_Error|null WP_Term instance (or array) on success, depending on the `$output` value.
  *                                     WP_Error if `$taxonomy` does not exist. Null for miscellaneous failure.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? array<string, mixed>|WP_Error|null : (
+ *         $output is 'ARRAY_N' ? list<mixed>|WP_Error|null : WP_Term|WP_Error|null
+ *     )
+ * )
  */
 function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
 	if ( empty( $term ) ) {
@@ -1101,6 +1108,13 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
  * @param string     $filter   Optional. How to sanitize term fields. Default 'raw'.
  * @return WP_Term|array|false WP_Term instance (or array) on success, depending on the `$output` value.
  *                             False if `$taxonomy` does not exist or `$term` was not found.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? array<string, mixed>|false : (
+ *         $output is 'ARRAY_N' ? list<mixed>|false : WP_Term|false
+ *     )
+ * )
  */
 function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
 
diff --git a/tests/phpstan/baselines/isset.property.neon b/tests/phpstan/baselines/isset.property.neon
index ab7d839e22002..f5e272b598f34 100644
--- a/tests/phpstan/baselines/isset.property.neon
+++ b/tests/phpstan/baselines/isset.property.neon
@@ -186,7 +186,7 @@ parameters:
 		-
 			message: '#^Property WP_Term\:\:\$term_id \(int\) in isset\(\) is not nullable\.$#'
 			identifier: isset.property
-			count: 1
+			count: 2
 			path: ../../../src/wp-includes/nav-menu.php
 		-
 			message: '#^Property WP_Post\:\:\$post_name \(string\) in isset\(\) is not nullable\.$#'
diff --git a/tests/phpstan/baselines/property.nonObject.neon b/tests/phpstan/baselines/property.nonObject.neon
index d242b9373685b..b996081f9b11b 100644
--- a/tests/phpstan/baselines/property.nonObject.neon
+++ b/tests/phpstan/baselines/property.nonObject.neon
@@ -183,11 +183,6 @@ parameters:
 			identifier: property.nonObject
 			count: 1
 			path: ../../../src/wp-includes/class-wp-customize-manager.php
-		-
-			message: '#^Cannot access property \$object_id on array\|WP_Error\|WP_Term\.$#'
-			identifier: property.nonObject
-			count: 1
-			path: ../../../src/wp-includes/class-wp-term-query.php
 		-
 			message: '#^Cannot access property \$term_id on string\|WP_Customize_Setting\.$#'
 			identifier: property.nonObject
@@ -218,18 +213,8 @@ parameters:
 			identifier: property.nonObject
 			count: 1
 			path: ../../../src/wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php
-		-
-			message: '#^Cannot access property \$parent on array\|object\.$#'
-			identifier: property.nonObject
-			count: 1
-			path: ../../../src/wp-includes/taxonomy.php
 		-
 			message: '#^Cannot access property \$template_name on array\.$#'
 			identifier: property.nonObject
 			count: 1
 			path: ../../../src/wp-includes/taxonomy.php
-		-
-			message: '#^Cannot access property \$term_id on array\|object\.$#'
-			identifier: property.nonObject
-			count: 4
-			path: ../../../src/wp-includes/taxonomy.php
diff --git a/tests/phpstan/baselines/property.notFound.neon b/tests/phpstan/baselines/property.notFound.neon
index c7d60d13061d2..460a5082ab0b8 100644
--- a/tests/phpstan/baselines/property.notFound.neon
+++ b/tests/phpstan/baselines/property.notFound.neon
@@ -293,6 +293,11 @@ parameters:
 			identifier: property.notFound
 			count: 2
 			path: ../../../src/wp-includes/class-walker-nav-menu.php
+		-
+			message: '#^Access to an undefined property WP_Error\|WP_Term\:\:\$object_id\.$#'
+			identifier: property.notFound
+			count: 1
+			path: ../../../src/wp-includes/class-wp-term-query.php
 		-
 			message: '#^Access to an undefined property WP_Query\:\:\$comments_by_type\.$#'
 			identifier: property.notFound

From 10804866f2864398dcc7e6d4daa9afd56bcb67d8 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:07:26 -0700
Subject: [PATCH 03/18] Add a conditional return type to `get_page_by_title()`.

The deprecated `get_page_by_title()` hands `$output` straight to `get_post()`,
which already declares a conditional `@phpstan-return`, but re-flattened the
result to `WP_Post|array|null` on the way out. Mirror `get_post()`'s branches so
the narrowing survives the call.

`src/wp-includes/deprecated.php` is on the `excludePaths.analyse` list in
`tests/phpstan/base.neon`, so nothing in the file is checked. The file is still
scanned for signatures, though, which is what makes the annotation reach callers
in plugins and themes -- the only consumers a deprecated function still has.

That exclusion is also why this commit bypasses the pre-commit hook: with only
an unanalysed file staged, PHPStan exits with "No files found to analyse" and
the hook reads that as a failure. The change was verified separately -- all
three branches resolve correctly at call sites, and PHPCS is clean.

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

diff --git a/src/wp-includes/deprecated.php b/src/wp-includes/deprecated.php
index 3b78d1610fdad..13c4f95f403d0 100644
--- a/src/wp-includes/deprecated.php
+++ b/src/wp-includes/deprecated.php
@@ -4569,6 +4569,13 @@ function _filter_query_attachment_filenames( $clauses ) {
  *                                 respectively. Default OBJECT.
  * @param string|array $post_type  Optional. Post type or array of post types. Default 'page'.
  * @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? non-empty-array<string, mixed>|null : (
+ *         $output is 'ARRAY_N' ? non-empty-array<int, mixed>|null : WP_Post|null
+ *     )
+ * )
  */
 function get_page_by_title( $page_title, $output = OBJECT, $post_type = 'page' ) {
 	_deprecated_function( __FUNCTION__, '6.2.0', 'WP_Query' );

From 8bc2330dcdf2302e54a8dee1046083266406041c Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:07:47 -0700
Subject: [PATCH 04/18] Add conditional return types for site and network
 queries.

`get_comments()` and `WP_Comment_Query::query()` narrow their return type on the
`count` and `fields` query vars, and `WP_Term_Query::query()` does the same. The
site and network queries take those same two query vars and shape their return
value the same way, but declared only the unnarrowed union, so every caller had
to widen back out by hand.

Declare the condition on `get_sites()`, `WP_Site_Query::query()`,
`get_networks()`, and `WP_Network_Query::query()`.

The network side needed its types filled in first. `WP_Network_Query::query()`,
`WP_Network_Query::get_networks()`, and `get_networks()` all declared a bare
`array|int`, which says nothing about what the array holds, and the
`networks_pre_query` filter documented its short-circuit value as `array|int|null`.
Give them the `WP_Network[]|int[]|int` the site query has used all along; the
prose in each of those docblocks already described exactly that.

One consequence worth noting: with `get_sites()` resolving to `array<int, WP_Site>`,
`wp_filter_oembed_result()` was caught handing `WP_Site::$blog_id` -- a numeric
string, for historical compatibility -- straight to `switch_to_blog()`, which
wants an int. The line immediately above it already casts for its comparison, so
cast here too.

Across the full tree this removes 56 static-analysis errors. The one it adds is
the counterpart of an error `WP_Site_Query::get_sites()` already carries: both
build their result with `array_map()` over `get_site()`/`get_network()`, which
are nullable, so the mapped array is not provably free of nulls.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/class-wp-network-query.php | 23 ++++++++++++++--------
 src/wp-includes/class-wp-site-query.php    |  6 ++++++
 src/wp-includes/embed.php                  |  2 +-
 src/wp-includes/ms-network.php             | 10 ++++++++--
 src/wp-includes/ms-site.php                |  6 ++++++
 5 files changed, 36 insertions(+), 11 deletions(-)

diff --git a/src/wp-includes/class-wp-network-query.php b/src/wp-includes/class-wp-network-query.php
index 7a5e9e7f41ffc..a7c747798f930 100644
--- a/src/wp-includes/class-wp-network-query.php
+++ b/src/wp-includes/class-wp-network-query.php
@@ -179,8 +179,14 @@ public function parse_query( $query = '' ) {
 	 * @since 4.6.0
 	 *
 	 * @param string|array $query Array or URL query string of parameters.
-	 * @return array|int List of WP_Network objects, a list of network IDs when 'fields' is set to 'ids',
-	 *                   or the number of networks when 'count' is passed as a query var.
+	 * @return WP_Network[]|int[]|int List of WP_Network objects, a list of network IDs when 'fields' is set
+	 *                                to 'ids', or the number of networks when 'count' is passed as a query var.
+	 *
+	 * @phpstan-return (
+	 *     $query is array{ count: true, ... } ? int : (
+	 *         $query is array{ fields: 'ids', ... } ? int[] : array<int, WP_Network>
+	 *     )
+	 * )
 	 */
 	public function query( $query ) {
 		$this->query_vars = wp_parse_args( $query );
@@ -192,8 +198,8 @@ public function query( $query ) {
 	 *
 	 * @since 4.6.0
 	 *
-	 * @return array|int List of WP_Network objects, a list of network IDs when 'fields' is set to 'ids',
-	 *                   or the number of networks when 'count' is passed as a query var.
+	 * @return WP_Network[]|int[]|int List of WP_Network objects, a list of network IDs when 'fields' is set
+	 *                                to 'ids', or the number of networks when 'count' is passed as a query var.
 	 */
 	public function get_networks() {
 		$this->parse_query();
@@ -234,10 +240,11 @@ public function get_networks() {
 		 * @since 5.6.0 The returned array of network data is assigned to the `networks` property
 		 *              of the current WP_Network_Query instance.
 		 *
-		 * @param array|int|null   $network_data Return an array of network data to short-circuit WP's network query,
-		 *                                       the network count as an integer if `$this->query_vars['count']` is set,
-		 *                                       or null to allow WP to run its normal queries.
-		 * @param WP_Network_Query $query        The WP_Network_Query instance, passed by reference.
+		 * @param WP_Network[]|int[]|int|null $network_data Return an array of network data to short-circuit WP's
+		 *                                                  network query, the network count as an integer if
+		 *                                                  `$this->query_vars['count']` is set, or null to allow WP
+		 *                                                  to run its normal queries.
+		 * @param WP_Network_Query            $query        The WP_Network_Query instance, passed by reference.
 		 */
 		$network_data = apply_filters_ref_array( 'networks_pre_query', array( $network_data, &$this ) );
 
diff --git a/src/wp-includes/class-wp-site-query.php b/src/wp-includes/class-wp-site-query.php
index 52ae228d90af0..aab8b511fcf83 100644
--- a/src/wp-includes/class-wp-site-query.php
+++ b/src/wp-includes/class-wp-site-query.php
@@ -265,6 +265,12 @@ public function parse_query( $query = '' ) {
 	 * @param string|array $query Array or URL query string of parameters.
 	 * @return WP_Site[]|int[]|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids',
 	 *                             or the number of sites when 'count' is passed as a query var.
+	 *
+	 * @phpstan-return (
+	 *     $query is array{ count: true, ... } ? int : (
+	 *         $query is array{ fields: 'ids', ... } ? int[] : array<int, WP_Site>
+	 *     )
+	 * )
 	 */
 	public function query( $query ) {
 		$this->query_vars = wp_parse_args( $query );
diff --git a/src/wp-includes/embed.php b/src/wp-includes/embed.php
index e87cf4ec57989..6a7501027a978 100644
--- a/src/wp-includes/embed.php
+++ b/src/wp-includes/embed.php
@@ -676,7 +676,7 @@ function get_oembed_response_data_for_url( $url, $args ) {
 		}
 
 		if ( $site && get_current_blog_id() !== (int) $site->blog_id ) {
-			switch_to_blog( $site->blog_id );
+			switch_to_blog( (int) $site->blog_id );
 			$switched_blog = true;
 		}
 	}
diff --git a/src/wp-includes/ms-network.php b/src/wp-includes/ms-network.php
index 8ab8819e268f2..35cc6bfc06dd7 100644
--- a/src/wp-includes/ms-network.php
+++ b/src/wp-includes/ms-network.php
@@ -57,8 +57,14 @@ function get_network( $network = null ) {
  *
  * @param string|array $args Optional. Array or string of arguments. See WP_Network_Query::parse_query()
  *                           for information on accepted arguments. Default empty array.
- * @return array|int List of WP_Network objects, a list of network IDs when 'fields' is set to 'ids',
- *                   or the number of networks when 'count' is passed as a query var.
+ * @return WP_Network[]|int[]|int List of WP_Network objects, a list of network IDs when 'fields' is set
+ *                                to 'ids', or the number of networks when 'count' is passed as a query var.
+ *
+ * @phpstan-return (
+ *     $args is array{ count: true, ... } ? int : (
+ *         $args is array{ fields: 'ids', ... } ? int[] : array<int, WP_Network>
+ *     )
+ * )
  */
 function get_networks( $args = array() ) {
 	$query = new WP_Network_Query();
diff --git a/src/wp-includes/ms-site.php b/src/wp-includes/ms-site.php
index f18189c30d5a3..342058156be01 100644
--- a/src/wp-includes/ms-site.php
+++ b/src/wp-includes/ms-site.php
@@ -441,6 +441,12 @@ function update_sitemeta_cache( $site_ids ) {
  *                           for information on accepted arguments. Default empty array.
  * @return WP_Site[]|int[]|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids',
  *                             or the number of sites when 'count' is passed as a query var.
+ *
+ * @phpstan-return (
+ *     $args is array{ count: true, ... } ? int : (
+ *         $args is array{ fields: 'ids', ... } ? int[] : array<int, WP_Site>
+ *     )
+ * )
  */
 function get_sites( $args = array() ) {
 	$query = new WP_Site_Query();

From b6c6df37b5d4938e1847f38297cf0b175b345830 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:08:25 -0700
Subject: [PATCH 05/18] Add a conditional return type to `get_users()`.

`get_users()` declared a bare `array`, so callers learned nothing about what it
holds -- not even that it is a list, let alone that the default query returns
`WP_User` objects. The shape is decided entirely by the `fields` query var, so
express that as a condition.

The branches follow `WP_User_Query::prepare_query()`: `'all'` and
`'all_with_meta'` give `WP_User` objects, a lone `'ID'` gives user IDs, any other
field name or list of field names gives the requested values, and anything
unrecognized -- including `fields` being absent, which is the common case --
falls back to `WP_User` objects. Ordering matters here: the catch-all for named
fields would otherwise swallow `'all'`, so the two object-returning values are
matched first and the same object type is repeated in the final `else`.

`WP_User_Query::get_results()` had to say more than `array` for this to hold at
the call site, since `get_users()` returns its result directly. Give it
`array<int, mixed>`, which is as precise as the method can honestly be: the value
type depends on the same `fields` query var, and the method takes no parameter to
condition on.

That leaves one error behind on `get_results()`, replacing the missing-value-type
one it had before. It reports accurately: the private `WP_User_Query::$results`
is still declared as a bare `array`. Typing that property is the next step and a
larger one -- it is assigned from the `users_pre_query` filter, from two
different `wpdb` methods, and from the object cache, and it holds `null` between
the filter call and the query, so closing this properly means reconciling all
four.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/class-wp-user-query.php | 3 ++-
 src/wp-includes/user.php                | 8 ++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/wp-includes/class-wp-user-query.php b/src/wp-includes/class-wp-user-query.php
index 3815023924489..61fc3edbc8ef9 100644
--- a/src/wp-includes/class-wp-user-query.php
+++ b/src/wp-includes/class-wp-user-query.php
@@ -962,7 +962,8 @@ protected function get_search_sql( $search, $columns, $wild = false ) {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @return array Array of results.
+	 * @return array<int, mixed> Array of results. Contains WP_User objects unless the 'fields' query var
+	 *                           requested specific fields, in which case it contains the requested values.
 	 */
 	public function get_results() {
 		return $this->results;
diff --git a/src/wp-includes/user.php b/src/wp-includes/user.php
index b4ab594038174..c26d88912c8b2 100644
--- a/src/wp-includes/user.php
+++ b/src/wp-includes/user.php
@@ -869,6 +869,14 @@ function get_user( $user_id ) {
  * @param array $args Optional. Arguments to retrieve users. See WP_User_Query::prepare_query()
  *                    for more information on accepted arguments.
  * @return array List of users.
+ *
+ * @phpstan-return (
+ *     $args is array{ fields: 'all'|'all_with_meta', ... } ? array<int, WP_User> : (
+ *         $args is array{ fields: 'ID'|'id', ... } ? array<int, non-negative-int> : (
+ *             $args is array{ fields: non-empty-string|non-empty-array<array-key, string>, ... } ? array<int, mixed> : array<int, WP_User>
+ *         )
+ *     )
+ * )
  */
 function get_users( $args = array() ) {
 

From 0e9daed916fbb3eb71d382f2caec0525f98e01e7 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:08:54 -0700
Subject: [PATCH 06/18] Add conditional return types for date and time format
 parameters.

Eight functions return an integer for one particular format string and a
formatted string for everything else. Every one of them already said so in
prose -- `current_time()` documents "Integer if `$type` is 'timestamp' or 'U',
string otherwise" -- while declaring a flat `int|string` that callers had to
re-narrow by hand.

Declare the condition on `current_time()` and `mysql2date()` in functions.php,
and on `get_the_date()`, `get_the_modified_date()`, `get_the_time()`,
`get_post_time()`, `get_the_modified_time()`, and `get_post_modified_time()` in
general-template.php. The `false` returned when there is no post, or when the
date cannot be parsed, precedes the format check in every case, so it appears in
both branches.

Two of these carry their answer in the default value: `get_post_time()` and
`get_post_modified_time()` default `$format` to 'U', so a bare call now resolves
to `int|false` rather than the full union.

Across the full tree this removes 13 static-analysis errors and introduces none.
Most of them are call sites that were handing one of these values to something
expecting a string -- `strtotime()`, `substr()`, `preg_match()`,
`wp_handle_upload()` -- where the integer branch could never have reached.

Two baseline patterns in `tests/phpstan/baselines/argument.type.neon` quote the
old, wider types in their message text, so they stop matching once the types
narrow. Update both to the text PHPStan now reports. They are the same two
errors as before, still baselined; only the spelling of the types inside them
changed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/functions.php              |  4 ++++
 src/wp-includes/general-template.php       | 12 ++++++++++++
 tests/phpstan/baselines/argument.type.neon |  9 +++++++--
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index 89d27f75e9f58..fe976fdaa1bf5 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -31,6 +31,8 @@
  * @param bool   $translate Whether the return date should be translated. Default true.
  * @return string|int|false Integer if `$format` is 'U' or 'G', string otherwise.
  *                          False on failure.
+ *
+ * @phpstan-return ( $format is 'U'|'G' ? int|false : string|false )
  */
 function mysql2date( $format, $date, $translate = true ) {
 	if ( empty( $date ) ) {
@@ -74,6 +76,8 @@ function mysql2date( $format, $date, $translate = true ) {
  *                     or PHP date format string (e.g. 'Y-m-d').
  * @param bool   $gmt  Optional. Whether to use GMT timezone. Default false.
  * @return int|string Integer if `$type` is 'timestamp' or 'U', string otherwise.
+ *
+ * @phpstan-return ( $type is 'timestamp'|'U' ? int : string )
  */
 function current_time( $type, $gmt = false ) {
 	// Don't use non-GMT timestamp, unless you know the difference and really need to.
diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php
index 2f37fbae50bbf..d1392a122ea04 100644
--- a/src/wp-includes/general-template.php
+++ b/src/wp-includes/general-template.php
@@ -3002,6 +3002,8 @@ function the_date( $format = '', $before = '', $after = '', $display = true ) {
  * @param string           $format Optional. PHP date format. Defaults to the 'date_format' option.
  * @param int|WP_Post|null $post   Optional. Post ID or WP_Post object. Default current post.
  * @return string|int|false Date the current post was written. False on failure.
+ *
+ * @phpstan-return ( $format is 'U'|'G' ? int|false : string|false )
  */
 function get_the_date( $format = '', $post = null ) {
 	$post = get_post( $post );
@@ -3069,6 +3071,8 @@ function the_modified_date( $format = '', $before = '', $after = '', $display =
  * @param string           $format Optional. PHP date format. Defaults to the 'date_format' option.
  * @param int|WP_Post|null $post   Optional. Post ID or WP_Post object. Default current post.
  * @return string|int|false Date the current post was modified. False on failure.
+ *
+ * @phpstan-return ( $format is 'U'|'G' ? int|false : string|false )
  */
 function get_the_modified_date( $format = '', $post = null ) {
 	$post = get_post( $post );
@@ -3128,6 +3132,8 @@ function the_time( $format = '' ) {
  * @param int|WP_Post|null $post   Post ID or post object. Default is global `$post` object.
  * @return string|int|false Formatted date string or Unix timestamp if `$format` is 'U' or 'G'.
  *                          False on failure.
+ *
+ * @phpstan-return ( $format is 'U'|'G' ? int|false : string|false )
  */
 function get_the_time( $format = '', $post = null ) {
 	$post = get_post( $post );
@@ -3165,6 +3171,8 @@ function get_the_time( $format = '', $post = null ) {
  * @param bool             $translate Whether to translate the time string. Default false.
  * @return string|int|false Formatted date string or Unix timestamp if `$format` is 'U' or 'G'.
  *                          False on failure.
+ *
+ * @phpstan-return ( $format is 'U'|'G' ? int|false : string|false )
  */
 function get_post_time( $format = 'U', $gmt = false, $post = null, $translate = false ) {
 	$post = get_post( $post );
@@ -3315,6 +3323,8 @@ function the_modified_time( $format = '' ) {
  *                                 Defaults to the 'time_format' option.
  * @param int|WP_Post|null $post   Optional. Post ID or WP_Post object. Default current post.
  * @return string|int|false Formatted date string or Unix timestamp. False on failure.
+ *
+ * @phpstan-return ( $format is 'U'|'G' ? int|false : string|false )
  */
 function get_the_modified_time( $format = '', $post = null ) {
 	$post = get_post( $post );
@@ -3354,6 +3364,8 @@ function get_the_modified_time( $format = '', $post = null ) {
  * @param bool             $translate Whether to translate the time string. Default false.
  * @return string|int|false Formatted date string or Unix timestamp if `$format` is 'U' or 'G'.
  *                          False on failure.
+ *
+ * @phpstan-return ( $format is 'U'|'G' ? int|false : string|false )
  */
 function get_post_modified_time( $format = 'U', $gmt = false, $post = null, $translate = false ) {
 	$post = get_post( $post );
diff --git a/tests/phpstan/baselines/argument.type.neon b/tests/phpstan/baselines/argument.type.neon
index 80844ad48e5ac..925f5cc743e04 100644
--- a/tests/phpstan/baselines/argument.type.neon
+++ b/tests/phpstan/baselines/argument.type.neon
@@ -729,7 +729,7 @@ parameters:
 			count: 1
 			path: ../../../src/wp-includes/class-wp-customize-manager.php
 		-
-			message: '#^Parameter \#1 \$postarr of function wp_insert_post expects array\{ID\?\: int, post_author\?\: int, post_date\?\: string, post_date_gmt\?\: string, post_content\?\: string, post_content_filtered\?\: string, post_title\?\: string, post_excerpt\?\: string, \.\.\., \.\.\.\}, array\<int\|string\|false\> given\.$#'
+			message: '#^Parameter \#1 \$postarr of function wp_insert_post expects array\{ID\?\: int, post_author\?\: int, post_date\?\: string, post_date_gmt\?\: string, post_content\?\: string, post_content_filtered\?\: string, post_title\?\: string, post_excerpt\?\: string, \.\.\., \.\.\.\}, array\<int\<min, \-1\>\|int\<1, max\>\|string\|false\> given\.$#'
 			identifier: argument.type
 			count: 1
 			path: ../../../src/wp-includes/class-wp-customize-manager.php
@@ -849,7 +849,7 @@ parameters:
 			count: 1
 			path: ../../../src/wp-includes/class-wp-widget.php
 		-
-			message: '#^Parameter \#1 \$postarr of function wp_insert_post expects array\{ID\?\: int, post_author\?\: int, post_date\?\: string, post_date_gmt\?\: string, post_content\?\: string, post_content_filtered\?\: string, post_title\?\: string, post_excerpt\?\: string, \.\.\., \.\.\.\}, array\{post_author\: int, post_date\: int\|string, post_date_gmt\: int\|string, post_content\: string, post_title\: string, post_category\: array\<string\>\|string, post_status\: ''draft''\|''publish''\} given\.$#'
+			message: '#^Parameter \#1 \$postarr of function wp_insert_post expects array\{ID\?\: int, post_author\?\: int, post_date\?\: string, post_date_gmt\?\: string, post_content\?\: string, post_content_filtered\?\: string, post_title\?\: string, post_excerpt\?\: string, \.\.\., \.\.\.\}, array\{post_author\: int, post_date\: string, post_date_gmt\: string, post_content\: string, post_title\: string, post_category\: array\<string\>\|string, post_status\: ''draft''\|''publish''\} given\.$#'
 			identifier: argument.type
 			count: 1
 			path: ../../../src/wp-includes/class-wp-xmlrpc-server.php
@@ -993,6 +993,11 @@ parameters:
 			identifier: argument.type
 			count: 2
 			path: ../../../src/wp-includes/general-template.php
+		-
+			message: '#^Parameter \#1 \$weekday_number of method WP_Locale\:\:get_weekday\(\) expects int, string\|false given\.$#'
+			identifier: argument.type
+			count: 2
+			path: ../../../src/wp-includes/general-template.php
 		-
 			message: '#^Parameter \#2 \$replace of function str_replace expects array\<string\>\|string, int\<1, max\> given\.$#'
 			identifier: argument.type

From 46c51a4251a240b8562d088b34c63078b3917246 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:09:34 -0700
Subject: [PATCH 07/18] Add a conditional return type to `WP_Theme::display()`.

`WP_Theme::get()` already resolves its return type from `$header`, giving
`string[]` for Tags and a string for the other known headers.
`WP_Theme::display()` wraps it, and its own docblock says "An array for Tags if
`$markup` is false, string otherwise" -- but it declared a flat
`string|array|false`, so everything `get()` had established was thrown away one
call later.

Declare the condition on both parameters: an array only when `$markup` is false
and the header is Tags, a string in every other case, and false throughout for a
header the theme does not have.

`WP_Theme::translate_header()` had to say more than `string|array` first, since
`display()` passes its value through on the way out. It is private, so it takes
the PHPStan types directly: `string|string[]` in and out.

Across the full tree this removes 57 static-analysis errors and introduces none.
Nearly all of them are `display()` results being concatenated or passed to
`sprintf()` -- in the themes list table, the theme editor, the upgrader skins,
update-core.php -- where the array branch could only ever have arrived for Tags,
and never at all once `$markup` was left at its default.

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

diff --git a/src/wp-includes/class-wp-theme.php b/src/wp-includes/class-wp-theme.php
index 87399e399a198..3a7866a364312 100644
--- a/src/wp-includes/class-wp-theme.php
+++ b/src/wp-includes/class-wp-theme.php
@@ -916,6 +916,14 @@ public function get( $header ) {
 	 * @param bool   $translate Optional. Whether to translate the header. Defaults to true.
 	 * @return string|array|false Processed header. An array for Tags if `$markup` is false, string otherwise.
 	 *                            False on failure.
+	 *
+	 * @phpstan-return (
+	 *     $markup is false
+	 *         ? ( $header is 'Tags'
+	 *             ? string[]|false
+	 *             : string|false )
+	 *         : string|false
+	 * )
 	 */
 	public function display( $header, $markup = true, $translate = true ) {
 		$value = $this->get( $header );
@@ -1056,6 +1064,9 @@ private function markup_header( $header, $value, $translate ) {
 	 * @param string       $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
 	 * @param string|array $value  Value to translate. An array for Tags header, string otherwise.
 	 * @return string|array Translated value. An array for Tags header, string otherwise.
+	 *
+	 * @phpstan-param string|string[] $value
+	 * @phpstan-return string|string[]
 	 */
 	private function translate_header( $header, $value ) {
 		switch ( $header ) {

From 1f2cfd56e1347f4effdb988a171f04fa99b03e6e Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:09:56 -0700
Subject: [PATCH 08/18] Add conditional return types for boolean output-shape
 flags.

Three functions take a boolean that decides not how much work they do but what
type comes back, and each already spelled the rule out in its `@return`
description while declaring the flat union.

`wp_insert_category()` and `wp_allow_comment()` both take `$wp_error`, and
return a `WP_Error` only when it is true. Follow the form `wp_insert_post()`
already uses for the same parameter, keyed on `false` so that omitting the
argument -- which is how nearly every caller invokes them -- resolves to the
narrow type rather than the union.

`single_month_title()` takes `$display`, echoing and returning null when it is
true and returning the title when it is false. Its siblings `single_cat_title()`,
`single_tag_title()`, and `single_term_title()` are already annotated this way;
this one was missed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-admin/includes/taxonomy.php   | 4 ++++
 src/wp-includes/comment.php          | 4 ++++
 src/wp-includes/general-template.php | 2 ++
 3 files changed, 10 insertions(+)

diff --git a/src/wp-admin/includes/taxonomy.php b/src/wp-admin/includes/taxonomy.php
index 470d36d55ffb1..f494f8abe3618 100644
--- a/src/wp-admin/includes/taxonomy.php
+++ b/src/wp-admin/includes/taxonomy.php
@@ -117,6 +117,10 @@ function wp_create_categories( $categories, $post_id = 0 ) {
  * @param bool  $wp_error Optional. Default false.
  * @return int|WP_Error The ID number of the new or updated Category on success. Zero or a WP_Error on failure,
  *                      depending on param `$wp_error`.
+ *
+ * @phpstan-return (
+ *     $wp_error is false ? int : int|WP_Error
+ * )
  */
 function wp_insert_category( $catarr, $wp_error = false ) {
 	$cat_defaults = array(
diff --git a/src/wp-includes/comment.php b/src/wp-includes/comment.php
index 03511ee4db709..f1ea45c5cd202 100644
--- a/src/wp-includes/comment.php
+++ b/src/wp-includes/comment.php
@@ -762,6 +762,10 @@ function sanitize_comment_cookies() {
  *                           Default false.
  * @return int|string|WP_Error Allowed comments return the approval status (0|1|'spam'|'trash').
  *                             If `$wp_error` is true, disallowed comments return a WP_Error.
+ *
+ * @phpstan-return (
+ *     $wp_error is false ? int|string : int|string|WP_Error
+ * )
  */
 function wp_allow_comment( $commentdata, $wp_error = false ) {
 	global $wpdb;
diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php
index d1392a122ea04..d6cf186ea4c93 100644
--- a/src/wp-includes/general-template.php
+++ b/src/wp-includes/general-template.php
@@ -1929,6 +1929,8 @@ function single_term_title( $prefix = '', $display = true ) {
  * @param string $prefix  Optional. What to display before the title.
  * @param bool   $display Optional. Whether to display or retrieve title. Default true.
  * @return string|false|null False if there's no valid title for the month. Title when retrieving.
+ *
+ * @phpstan-return ( $display is true ? false|null : string|false )
  */
 function single_month_title( $prefix = '', $display = true ) {
 	global $wp_locale;

From 792f9e98a038acba899c9f415f754e05d0e62445 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:10:11 -0700
Subject: [PATCH 09/18] Type the shape of the `WP_Theme` header pipeline.

`WP_Theme::display()` gained a conditional return type in the previous commit,
but the two private methods it hands its value to were left saying only that the
result is a string or an array. Both say something more specific.

`sanitize_header()` is where the array comes from: it takes a string in every
case and returns one back, except for Tags, which it explodes on commas. That is
a condition on `$header`. Giving it one also supplies the value type its
`@return` was missing, which is where the one error this removes came from.

`translate_header()` never changes the shape it is handed. Every branch either
returns `$value` untouched or replaces it with `translate()`, so a string in
means a string out and an array in means an array out. That is a condition on
`$value`, not on `$header` -- the Tags branch returns the value as-is when it is
empty or the feature list is unavailable, so even Tags can come back as a string.

The two together mean the shape is now stated at each step it passes through:
`sanitize_header()` decides it from the header name, `get()` reports it,
`translate_header()` preserves it, and `display()` resolves it for callers.

Also drop the `@phpstan-param` and `@phpstan-return` added to
`translate_header()` in the previous commit. `string[]` is ordinary PHPDoc, so
the plain tags carry it -- PHPStan reports the same 87 errors for the file either
way. Only the conditional genuinely needs a prefixed tag.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/class-wp-theme.php | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/src/wp-includes/class-wp-theme.php b/src/wp-includes/class-wp-theme.php
index 3a7866a364312..2335918979a8a 100644
--- a/src/wp-includes/class-wp-theme.php
+++ b/src/wp-includes/class-wp-theme.php
@@ -957,7 +957,9 @@ public function display( $header, $markup = true, $translate = true ) {
 	 *                       'ThemeURI', 'AuthorURI', 'Status', 'Tags', 'RequiresWP', 'RequiresPHP',
 	 *                       'UpdateURI'.
 	 * @param string $value  Value to sanitize.
-	 * @return string|array An array for Tags header, string otherwise.
+	 * @return string|string[] An array for Tags header, string otherwise.
+	 *
+	 * @phpstan-return ( $header is 'Tags' ? string[] : string )
 	 */
 	private function sanitize_header( $header, $value ) {
 		switch ( $header ) {
@@ -1061,12 +1063,11 @@ private function markup_header( $header, $value, $translate ) {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string       $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
-	 * @param string|array $value  Value to translate. An array for Tags header, string otherwise.
-	 * @return string|array Translated value. An array for Tags header, string otherwise.
+	 * @param string          $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
+	 * @param string|string[] $value  Value to translate. An array for Tags header, string otherwise.
+	 * @return string|string[] Translated value. An array for Tags header, string otherwise.
 	 *
-	 * @phpstan-param string|string[] $value
-	 * @phpstan-return string|string[]
+	 * @phpstan-return ( $value is string ? string : string[] )
 	 */
 	private function translate_header( $header, $value ) {
 		switch ( $header ) {

From 323670c51d90e152fead638c9d3005867c6ee0a0 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:10:39 -0700
Subject: [PATCH 10/18] Add conditional return types to `has_filter()` and
 `has_action()`.

Both functions have three distinct return values selected by their arguments: a
bool for whether anything at all is hooked when no callback is given, the
callback's priority as an int when one is, and a bool again when a specific
priority is also supplied. The docblock has described that in prose since 6.9.0
added `$priority`, while the declared type stayed `bool|int`, so callers had to
re-establish which of the three they were holding.

Declare the condition on `has_filter()`, `has_action()`, and the
`WP_Hook::has_filter()` they both ultimately reach.

This resolves eight errors across the tree, all of the same shape: a priority is
read back out of `has_filter()` and handed straight to `add_filter()` or
`remove_filter()`, which want an int. `do_blocks()` is the clearest case --
it takes the priority of `wpautop`, removes the filter, and re-adds a restore
callback at `$priority + 1`. Guarding with `false !== $priority` used to leave
`true|int`, so both the arithmetic and the hook calls were checked against a type
that included a bool. The same pattern appears in `wp_filter_content_tags()`,
`wp_common_block_scripts_and_styles()`, and `WP_Widget_Text`.

PHPStan reports `return.unusedType` against `has_filter()` and `has_action()`
anyway, claiming neither returns an int. That is a bug in PHPStan, reported as
phpstan/phpstan#15268: when it combines the branches of a conditional return type
for a call whose argument is not narrow enough to select one, it drops the int
from an `int|false` branch. So each wrapper is handed a type that has already
lost the int before it can return it. The fault depends on the PHP version
PHPStan itself runs on, not on the analysed `phpVersion`: correct on PHP 8.2,
wrong on 8.3, 8.4 and 8.5, identically across PHPStan 2.2.13 through 2.3.x-dev.

Suppress it in `phpstan.neon.dist` rather than with `@phpstan-ignore` comments.
An inline ignore has to match, and on PHP 8.2 there is nothing to match, so it
becomes an `ignore.unmatchedIdentifier` error of its own -- which is
non-ignorable, and would report in any editor configured against 8.2 while CI on
a newer PHP stayed green. The config entry takes `reportUnmatched: false` and so
is silent either way. Remove it, and its comment, once the upstream fix ships.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 phpstan.neon.dist                 | 26 ++++++++++++++++++++++++++
 src/wp-includes/class-wp-hook.php |  7 +++++++
 src/wp-includes/plugin.php        | 14 ++++++++++++++
 3 files changed, 47 insertions(+)

diff --git a/phpstan.neon.dist b/phpstan.neon.dist
index c2979636e776f..873c7fbfc17e3 100644
--- a/phpstan.neon.dist
+++ b/phpstan.neon.dist
@@ -121,6 +121,32 @@ parameters:
 			path: src/wp-includes/compat.php
 			reportUnmatched: false
 
+		# Level 4:
+		# has_filter() and has_action() declare a conditional return type: a bool when called without
+		# a callback, the callback's priority as an int otherwise, and false when it is not attached.
+		# The annotation is correct, and every call site resolves to the right one of those.
+		#
+		# Both functions are thin wrappers, has_action() over has_filter() and has_filter() over
+		# WP_Hook::has_filter(). When PHPStan combines the branches of a conditional return type for
+		# a call whose argument is not narrow enough to select one, it drops the int from the
+		# int|false branch, so the type these two receive back from their callee has already lost it.
+		# return.unusedType then reports that they never return an int. They do: the priority.
+		#
+		# The fault is PHPStan's, and it depends on the PHP version PHPStan itself runs on rather
+		# than on the analysed phpVersion. Correct on PHP 8.2, wrong on 8.3, 8.4 and 8.5, identically
+		# across PHPStan 2.2.13 through 2.3.x-dev. See https://github.com/phpstan/phpstan/issues/15268.
+		#
+		# This lives here rather than in a baseline because there is no work to do in WordPress: the
+		# annotation is right and the report is not. reportUnmatched: false because whether the error
+		# appears at all depends on the PHP version running PHPStan, so an entry that had to match
+		# would fail for anyone on 8.2. It also means this lapses quietly once the fix is released,
+		# at which point remove the entry and this comment.
+		-
+			message: '#^Function has_(filter|action)\(\) never returns int so it can be removed from the return type\.$#'
+			identifier: return.unusedType
+			path: src/wp-includes/plugin.php
+			reportUnmatched: false
+
 		# Level 5:
 		# substr_compare()'s $length has always accepted null, meaning "compare the full length". PHP 7.4 spelled
 		# that `int $length = null`, where the null default makes the parameter implicitly nullable, and PHP 8.0
diff --git a/src/wp-includes/class-wp-hook.php b/src/wp-includes/class-wp-hook.php
index 1718878308300..0d04bef31b642 100644
--- a/src/wp-includes/class-wp-hook.php
+++ b/src/wp-includes/class-wp-hook.php
@@ -250,6 +250,13 @@ public function remove_filter( $hook_name, $callback, $priority ) {
 	 *                  If `$callback` and `$priority` are both provided, a boolean is returned
 	 *                  for whether the specific function is registered at that priority.
 	 * @phpstan-param Maybe_Callable|false $callback
+	 * @phpstan-return (
+	 *     $callback is false
+	 *         ? bool
+	 *         : ( $priority is int
+	 *             ? bool
+	 *             : int|false )
+	 * )
 	 */
 	public function has_filter( $hook_name = '', $callback = false, $priority = false ) {
 		if ( false === $callback ) {
diff --git a/src/wp-includes/plugin.php b/src/wp-includes/plugin.php
index 38e88aa96bb00..82114f270b711 100644
--- a/src/wp-includes/plugin.php
+++ b/src/wp-includes/plugin.php
@@ -285,6 +285,13 @@ function apply_filters_ref_array( $hook_name, $args ) {
  *                  If `$callback` and `$priority` are both provided, a boolean is returned
  *                  for whether the specific function is registered at that priority.
  * @phpstan-param Maybe_Callable|false $callback
+ * @phpstan-return (
+ *     $callback is false
+ *         ? bool
+ *         : ( $priority is int
+ *             ? bool
+ *             : int|false )
+ * )
  */
 function has_filter( $hook_name, $callback = false, $priority = false ) {
 	global $wp_filter;
@@ -600,6 +607,13 @@ function do_action_ref_array( $hook_name, $args ) {
  *                  If `$callback` and `$priority` are both provided, a boolean is returned
  *                  for whether the specific function is registered at that priority.
  * @phpstan-param Maybe_Callable|false $callback
+ * @phpstan-return (
+ *     $callback is false
+ *         ? bool
+ *         : ( $priority is int
+ *             ? bool
+ *             : int|false )
+ * )
  */
 function has_action( $hook_name, $callback = false, $priority = false ) {
 	return has_filter( $hook_name, $callback, $priority );

From 4f7bb29d710561a7ce4284fd303c5797cf2fa38a Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 17:34:57 -0700
Subject: [PATCH 11/18] Add conditional return types for two private helpers,
 and correct one `@return`.

`_get_block_templates_files()` returns null for a `$template_type` that is
neither 'wp_template' nor 'wp_template_part', and an array of template files for
either of those. Both are the only outcomes, so the condition is exact. Giving it
one also supplies the value type its `@return` was missing, which is what removes
the five errors below.

`wp_find_hierarchy_loop_tortoise_hare()` returns an array of the loop's members
when `$_return_loop` is set and an arbitrary member's ID otherwise, both by way of
the same `$_return_loop ? $return : $tortoise` expression, or false when no loop
was found. Only the array case is worth stating, since the scalar is whatever the
`$callback` returns and stays `mixed`; note the `false` in both. While there, say
in the description that false means no loop, which was not written down anywhere.

The element type on the first is `array<array-key, mixed>` rather than the
`array<string, mixed>` these items actually are. The items come back from
`_add_block_template_info()` and `_add_block_template_part_area_info()`, both of
which declare a bare `array`, so the stricter type is correct but not checkable
from here. Typing those two is its own change.

Separately, `_get_block_template_file()` claimed to return "Array with template
metadata if $template_type is one of 'wp_template' or 'wp_template_part', null
otherwise". The second half is wrong: a matched `$template_type` also returns null
when the theme has no file for `$slug`, which is the common case for any slug the
theme does not define. Say both reasons. No conditional for this one, because
with null reachable from either branch there is nothing left to distinguish.

Across the full tree this removes six static-analysis errors and introduces none.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/block-template-utils.php | 8 ++++++--
 src/wp-includes/functions.php            | 6 +++++-
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/wp-includes/block-template-utils.php b/src/wp-includes/block-template-utils.php
index 96d2372694200..78cd1bbdc15f5 100644
--- a/src/wp-includes/block-template-utils.php
+++ b/src/wp-includes/block-template-utils.php
@@ -319,8 +319,8 @@ function _get_block_templates_paths( $base_directory ) {
  * @param string $template_type Template type. Either 'wp_template' or 'wp_template_part'.
  * @param string $slug          Template slug.
  * @return array|null {
- *     Array with template metadata if $template_type is one of 'wp_template' or 'wp_template_part',
- *     null otherwise.
+ *     Array with template metadata, or null if `$template_type` is neither 'wp_template' nor
+ *     'wp_template_part', or if the theme has no template file for `$slug`.
  *
  *     @type string   $slug      Template slug.
  *     @type string   $path      Template file path.
@@ -392,6 +392,10 @@ function _get_block_template_file( $template_type, $slug ) {
  * }
  *
  * @return array|null Template files on success, null if `$template_type` is not matched.
+ *
+ * @phpstan-return (
+ *     $template_type is 'wp_template'|'wp_template_part' ? list<array<array-key, mixed>> : null
+ * )
  */
 function _get_block_templates_files( $template_type, $query = array() ) {
 	if ( 'wp_template' !== $template_type && 'wp_template_part' !== $template_type ) {
diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index fe976fdaa1bf5..5dd1916737796 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -7302,7 +7302,11 @@ function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_arg
  *                                to true if you already know the given $start is part of a loop (otherwise
  *                                the returned array might include branches). Default false.
  * @return mixed Scalar ID of some arbitrary member of the loop, or array of IDs of all members of loop if
- *               $_return_loop
+ *               $_return_loop. False if no loop was found.
+ *
+ * @phpstan-return (
+ *     $_return_loop is true ? array<array-key, true>|false : mixed
+ * )
  */
 function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = array(), $callback_args = array(), $_return_loop = false ) {
 	$tortoise        = $start;

From b27a94177109b71eb728eaf8096b1e000d79213a Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 19:53:57 -0700
Subject: [PATCH 12/18] Spell the `has_filter()` union as `false|int` and drop
 the PHPStan workaround.

The conditional return types on `has_filter()`, `has_action()`, and
`WP_Hook::has_filter()` tripped a PHPStan bug that dropped the `int` from their
`int|false` branch, so `return.unusedType` claimed each wrapper never returns an
int. Keeping the tree clean needed an `ignoreErrors` entry, reported upstream as
phpstan/phpstan#15268.

The bug turns out to depend on the order the union is written in, and on the
branch it sits in: `int|false` in the else branch loses its `int`, while
`false|int` in the same place, or `int|false` in the then branch, does not. The
two spellings denote the same type and callers cannot tell them apart, so write
the one that works and delete the suppression along with its comment.

Verified with each of four PHP builds running PHPStan against
`phpstan.neon.dist`: no errors on 8.2.33, 8.3.33, 8.4.25, or 8.5.9, where before
this every version from 8.3 up needed the entry. Call sites are unchanged --
`has_filter( $hook )` still resolves to `bool`, `has_filter( $hook, $cb )` to
`int|false`, and `has_filter( $hook, $cb, 10 )` to `bool` -- and the full analysis
is unchanged at 27,760 errors, with none introduced and none resolved.

The spelling comes from the PHPStan types in
https://github.com/WordPress/wordpress-develop/pull/13530, which writes
`($callback is false ? bool : false|int)` and so never met this. That version
predates the `$priority` parameter added in 6.9.0, however: it reports `false|int`
for a call that passes a specific priority, where the function returns a bool. The
three-way condition is kept here for that reason.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 phpstan.neon.dist                 | 26 --------------------------
 src/wp-includes/class-wp-hook.php |  2 +-
 src/wp-includes/plugin.php        |  4 ++--
 3 files changed, 3 insertions(+), 29 deletions(-)

diff --git a/phpstan.neon.dist b/phpstan.neon.dist
index 873c7fbfc17e3..c2979636e776f 100644
--- a/phpstan.neon.dist
+++ b/phpstan.neon.dist
@@ -121,32 +121,6 @@ parameters:
 			path: src/wp-includes/compat.php
 			reportUnmatched: false
 
-		# Level 4:
-		# has_filter() and has_action() declare a conditional return type: a bool when called without
-		# a callback, the callback's priority as an int otherwise, and false when it is not attached.
-		# The annotation is correct, and every call site resolves to the right one of those.
-		#
-		# Both functions are thin wrappers, has_action() over has_filter() and has_filter() over
-		# WP_Hook::has_filter(). When PHPStan combines the branches of a conditional return type for
-		# a call whose argument is not narrow enough to select one, it drops the int from the
-		# int|false branch, so the type these two receive back from their callee has already lost it.
-		# return.unusedType then reports that they never return an int. They do: the priority.
-		#
-		# The fault is PHPStan's, and it depends on the PHP version PHPStan itself runs on rather
-		# than on the analysed phpVersion. Correct on PHP 8.2, wrong on 8.3, 8.4 and 8.5, identically
-		# across PHPStan 2.2.13 through 2.3.x-dev. See https://github.com/phpstan/phpstan/issues/15268.
-		#
-		# This lives here rather than in a baseline because there is no work to do in WordPress: the
-		# annotation is right and the report is not. reportUnmatched: false because whether the error
-		# appears at all depends on the PHP version running PHPStan, so an entry that had to match
-		# would fail for anyone on 8.2. It also means this lapses quietly once the fix is released,
-		# at which point remove the entry and this comment.
-		-
-			message: '#^Function has_(filter|action)\(\) never returns int so it can be removed from the return type\.$#'
-			identifier: return.unusedType
-			path: src/wp-includes/plugin.php
-			reportUnmatched: false
-
 		# Level 5:
 		# substr_compare()'s $length has always accepted null, meaning "compare the full length". PHP 7.4 spelled
 		# that `int $length = null`, where the null default makes the parameter implicitly nullable, and PHP 8.0
diff --git a/src/wp-includes/class-wp-hook.php b/src/wp-includes/class-wp-hook.php
index 0d04bef31b642..9a4d4a2c5eeca 100644
--- a/src/wp-includes/class-wp-hook.php
+++ b/src/wp-includes/class-wp-hook.php
@@ -255,7 +255,7 @@ public function remove_filter( $hook_name, $callback, $priority ) {
 	 *         ? bool
 	 *         : ( $priority is int
 	 *             ? bool
-	 *             : int|false )
+	 *             : false|int )
 	 * )
 	 */
 	public function has_filter( $hook_name = '', $callback = false, $priority = false ) {
diff --git a/src/wp-includes/plugin.php b/src/wp-includes/plugin.php
index 82114f270b711..a3e9afacdb8dc 100644
--- a/src/wp-includes/plugin.php
+++ b/src/wp-includes/plugin.php
@@ -290,7 +290,7 @@ function apply_filters_ref_array( $hook_name, $args ) {
  *         ? bool
  *         : ( $priority is int
  *             ? bool
- *             : int|false )
+ *             : false|int )
  * )
  */
 function has_filter( $hook_name, $callback = false, $priority = false ) {
@@ -612,7 +612,7 @@ function do_action_ref_array( $hook_name, $args ) {
  *         ? bool
  *         : ( $priority is int
  *             ? bool
- *             : int|false )
+ *             : false|int )
  * )
  */
 function has_action( $hook_name, $callback = false, $priority = false ) {

From 3f38f79cf04a18495494f2bc943f9efd975700f9 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 20:41:07 -0700
Subject: [PATCH 13/18] Bring in the conditional return types from the
 WordPress stubs' function map.

The function map behind the WordPress stubs has carried conditional return types
for years, and https://github.com/WordPress/wordpress-develop/pull/13530 proposes
moving them into core's own docblocks. Take the conditional ones from that set
here, so this branch covers the same ground rather than half of it. That PR is a
draft and expected to keep moving; where the two disagree, settling it is its
business rather than this branch's.

Only the conditional `@phpstan-return` tags are taken. That PR also adds
`@phpstan-pure`, `@phpstan-impure`, `@phpstan-assert-if-true` and a number of plain
`@phpstan-param` types, none of which have anything to do with conditional
returns; those are left to it. The exception is `@phpstan-template`, kept together
with the `@phpstan-param T $x` that binds it, wherever a condition is written in
terms of the template rather than of a parameter -- `maybe_serialize()`,
`rest_sanitize_boolean()`, `wp_http_validate_url()`, `add_cssclass()`,
`sanitize_sql_orderby()`, `translate_plural()` -- since without the declaration the
type does not parse.

Fifty functions across twenty-five files, all of the kinds this branch has been
working through already:

- A flag deciding whether failure arrives as a `WP_Error` or as `false`:
  `wp_schedule_single_event()`, `wp_schedule_event()`, `wp_reschedule_event()`,
  `wp_unschedule_event()`, `wp_clear_scheduled_hook()`, `wp_unschedule_hook()`,
  `wp_set_comment_status()`, `wp_update_comment()`, `wp_insert_link()`.
- An argument selecting the shape of the result: `wp_list_categories()` and
  `wp_generate_tag_cloud()` on `echo` and `format`, `paginate_links()` on `type`,
  `get_categories()` and `get_tags()` on `fields`, `get_user_by()` on `$field`,
  `wp_debug_backtrace_summary()` on `$pretty`, `WP_Dependencies::query()` on
  `$status`.
- A literal argument value the result follows from: `size_format()`,
  `bool_from_yn()`, `validate_file()`, `zeroise()`, `get_tag_regex()`,
  `maybe_serialize()`, `block_version()`, `taxonomy_exists()`, `tag_exists()`,
  `is_term()`, `sanitize_term_field()`, `wp_is_post_revision()`,
  `wp_unique_prefixed_id()`, `translate_plural()`.
- Emptiness or the type of the input deciding what can come back at all:
  `wp_get_link_cats()`, `add_cssclass()`, `delete_plugins()`, `validate_plugin()`,
  `wp_extract_urls()`, `path_is_absolute()`, `wp_is_numeric_array()`,
  `wp_is_uuid()`, `sanitize_sql_orderby()`, `wp_http_validate_url()`,
  `has_shortcode()`, `is_wp_error()`, `rest_ensure_response()`,
  `rest_sanitize_boolean()`, `get_user()`, `get_the_permalink()`,
  `get_post_permalink()`, `addslashes_gpc()`, `get_block_wrapper_attributes()`.

Formatted the way the rest of core's conditional types are written: spaces inside
the parentheses and the array-shape braces, a blank docblock line separating the
PHPStan tags from the standard ones, and the two that ran long broken across lines
as the longer ones here already are.

Twelve of the set overlap with work already on this branch and are left alone for
now; each is compared on its own merits in what follows. Eight more did not apply
cleanly, five because the function already carries a conditional type on trunk and
two because an attribute sits between the docblock and the declaration; those are
handled separately too.

One baseline entry falls away: an `if.alwaysFalse` in the REST comments controller
that a narrowed type makes reachable again.

Verified against `phpstan.neon.dist` with PHPStan running on PHP 8.2.33 and
8.3.33: no errors on either, and PHPCS reports nothing on the added lines.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-admin/includes/bookmark.php            |  4 +++
 src/wp-admin/includes/menu.php                |  4 +++
 src/wp-admin/includes/plugin.php              |  4 +++
 src/wp-admin/includes/taxonomy.php            |  6 ++++
 src/wp-includes/blocks.php                    |  2 ++
 src/wp-includes/category-template.php         |  4 +++
 src/wp-includes/category.php                  | 32 +++++++++++++++++++
 src/wp-includes/class-wp-block-supports.php   |  2 ++
 src/wp-includes/class-wp-dependencies.php     | 10 ++++++
 src/wp-includes/comment.php                   |  4 +++
 src/wp-includes/cron.php                      | 12 +++++++
 src/wp-includes/deprecated.php                | 12 +++++++
 src/wp-includes/formatting.php                | 14 ++++++++
 src/wp-includes/functions.php                 | 28 ++++++++++++++++
 src/wp-includes/general-template.php          |  6 ++++
 src/wp-includes/http.php                      |  4 +++
 .../l10n/class-wp-translations.php            |  4 +++
 src/wp-includes/link-template.php             |  4 +++
 src/wp-includes/load.php                      |  2 ++
 src/wp-includes/pluggable.php                 |  6 ++++
 src/wp-includes/rest-api.php                  |  6 ++++
 src/wp-includes/revision.php                  |  6 ++++
 src/wp-includes/shortcodes.php                |  2 ++
 src/wp-includes/taxonomy.php                  | 10 ++++++
 src/wp-includes/user.php                      |  2 ++
 tests/phpstan/baselines/if.alwaysFalse.neon   |  5 ---
 26 files changed, 190 insertions(+), 5 deletions(-)

diff --git a/src/wp-admin/includes/bookmark.php b/src/wp-admin/includes/bookmark.php
index c64bac144c588..7fa308c93172a 100644
--- a/src/wp-admin/includes/bookmark.php
+++ b/src/wp-admin/includes/bookmark.php
@@ -122,6 +122,8 @@ function wp_delete_link( $link_id ) {
  *
  * @param int $link_id Link ID to look up.
  * @return int[] The IDs of the requested link's categories.
+ *
+ * @phpstan-return ( $link_id is empty ? array{ } : array<int, int<1, max>> )
  */
 function wp_get_link_cats( $link_id = 0 ) {
 	$cats = wp_get_object_terms( $link_id, 'link_category', array( 'fields' => 'ids' ) );
@@ -170,6 +172,8 @@ function get_link_to_edit( $link ) {
  * }
  * @param bool  $wp_error Optional. Whether to return a WP_Error object on failure. Default false.
  * @return int|WP_Error The link ID on success. The value 0 or WP_Error on failure.
+ *
+ * @phpstan-return ( $wp_error is false ? int<0, max> : int<0, max>|WP_Error )
  */
 function wp_insert_link( $linkdata, $wp_error = false ) {
 	global $wpdb;
diff --git a/src/wp-admin/includes/menu.php b/src/wp-admin/includes/menu.php
index a95cf9e33956e..f1c2985e93e8e 100644
--- a/src/wp-admin/includes/menu.php
+++ b/src/wp-admin/includes/menu.php
@@ -208,6 +208,10 @@
  * @param string $class_to_add The CSS class to add.
  * @param string $classes      The string to add the CSS class to.
  * @return string The string with the CSS class added.
+ *
+ * @phpstan-template T of string
+ * @phpstan-param T $class_to_add
+ * @phpstan-return ( $classes is empty ? T : non-empty-string )
  */
 function add_cssclass( $class_to_add, $classes ) {
 	if ( empty( $classes ) ) {
diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index 53d933d07e4d8..a34d473bca650 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -906,6 +906,8 @@ function activate_plugins( $plugins, $redirect = '', $network_wide = false, $sil
  * @param string   $deprecated Not used.
  * @return bool|null|WP_Error True on success, false if `$plugins` is empty, `WP_Error` on failure.
  *                            `null` if filesystem credentials are required to proceed.
+ *
+ * @phpstan-return ( $plugins is empty ? false : true|null|WP_Error )
  */
 function delete_plugins( $plugins, $deprecated = '' ) {
 	global $wp_filesystem;
@@ -1111,6 +1113,8 @@ function validate_active_plugins() {
  *
  * @param string $plugin Path to the plugin file relative to the plugins directory.
  * @return int|WP_Error 0 on success, WP_Error on failure.
+ *
+ * @phpstan-return ( $plugin is empty ? WP_Error : 0|WP_Error )
  */
 function validate_plugin( $plugin ) {
 	if ( validate_file( $plugin ) ) {
diff --git a/src/wp-admin/includes/taxonomy.php b/src/wp-admin/includes/taxonomy.php
index f494f8abe3618..dbdab1af4fab8 100644
--- a/src/wp-admin/includes/taxonomy.php
+++ b/src/wp-admin/includes/taxonomy.php
@@ -222,6 +222,12 @@ function wp_update_category( $catarr ) {
  * @return mixed Returns null if the term does not exist.
  *               Returns an array of the term ID and the term taxonomy ID if the pairing exists.
  *               Returns 0 if term ID 0 is passed to the function.
+ *
+ * @phpstan-return (
+ *     $tag_name is 0
+ *         ? 0
+ *         : ( $tag_name is '' ? null : array{ term_id: string, term_taxonomy_id: string }|null )
+ * )
  */
 function tag_exists( $tag_name ) {
 	return term_exists( $tag_name, 'post_tag' );
diff --git a/src/wp-includes/blocks.php b/src/wp-includes/blocks.php
index 487c2765ac249..beaf08d4022c6 100644
--- a/src/wp-includes/blocks.php
+++ b/src/wp-includes/blocks.php
@@ -2682,6 +2682,8 @@ function _wp_apply_block_content_filters( $content, $context = '', &$seen_ids =
  *
  * @param string $content Content to test.
  * @return int The block format version is 1 if the content contains one or more blocks, 0 otherwise.
+ *
+ * @phpstan-return ( $content is '' ? 0 : 0|1 )
  */
 function block_version( $content ) {
 	return has_blocks( $content ) ? 1 : 0;
diff --git a/src/wp-includes/category-template.php b/src/wp-includes/category-template.php
index f268f93cbc461..1d456f309de3d 100644
--- a/src/wp-includes/category-template.php
+++ b/src/wp-includes/category-template.php
@@ -534,6 +534,8 @@ function wp_dropdown_categories( $args = '' ) {
  * }
  * @return void|string|false Void if 'echo' argument is true, HTML list of categories if 'echo' is false.
  *                           False if the taxonomy does not exist.
+ *
+ * @phpstan-return ( $args is array{ echo: false|0, ... } ? string|false : false|void )
  */
 function wp_list_categories( $args = '' ) {
 	$defaults = array(
@@ -849,6 +851,8 @@ function default_topic_count_scale( $count ) {
  *                                                0, 1, or their bool equivalents.
  * }
  * @return string|string[] Tag cloud as a string or an array, depending on 'format' argument.
+ *
+ * @phpstan-return ( $args is array{ format: 'array', ... } ? array<int, string> : string )
  */
 function wp_generate_tag_cloud( $tags, $args = '' ) {
 	$defaults = array(
diff --git a/src/wp-includes/category.php b/src/wp-includes/category.php
index 37f41855c1b45..6f35c5db0bbf4 100644
--- a/src/wp-includes/category.php
+++ b/src/wp-includes/category.php
@@ -22,6 +22,24 @@
  *     @type string $taxonomy Taxonomy to retrieve terms for. Default 'category'.
  * }
  * @return array List of category objects.
+ *
+ * @phpstan-return (
+ *     $args is array{ fields: 'count', ... }
+ *         ? list<numeric-string>
+ *         : (
+ *             $args is array{ fields: 'names'|'slugs', ... }
+ *                 ? list<string>
+ *                 : (
+ *                     $args is array{ fields: 'id=>name'|'id=>slug', ... }
+ *                         ? array<int, string>
+ *                         : (
+ *                             $args is array{ fields: 'id=>parent', ... }
+ *                                 ? array<int, int>
+ *                                 : ( $args is array{ fields: 'ids'|'tt_ids', ... } ? list<int> : array<int, WP_Term> )
+ *                         )
+ *                 )
+ *         )
+ * )
  */
 function get_categories( $args = '' ) {
 	$defaults = array( 'taxonomy' => 'category' );
@@ -307,6 +325,20 @@ function sanitize_category_field( $field, $value, $cat_id, $context ) {
  * }
  * @return WP_Term[]|int|WP_Error Array of 'post_tag' term objects, a count thereof,
  *                                or WP_Error if any of the taxonomies do not exist.
+ *
+ * @phpstan-return (
+ *     $args is array{ fields: 'names'|'slugs', ... }
+ *         ? list<string>
+ *         : (
+ *             $args is array{ fields: 'id=>name'|'id=>slug', ... }
+ *                 ? array<int, string>
+ *                 : (
+ *                     $args is array{ fields: 'id=>parent', ... }
+ *                         ? array<int, int>
+ *                         : ( $args is array{ fields: 'ids'|'tt_ids', ... } ? list<int> : array<int, WP_Term> )
+ *                 )
+ *         )
+ * )|WP_Error
  */
 function get_tags( $args = '' ) {
 	$defaults = array( 'taxonomy' => 'post_tag' );
diff --git a/src/wp-includes/class-wp-block-supports.php b/src/wp-includes/class-wp-block-supports.php
index cf2d84f3b6756..c065cd911de04 100644
--- a/src/wp-includes/class-wp-block-supports.php
+++ b/src/wp-includes/class-wp-block-supports.php
@@ -197,6 +197,8 @@ private function register_attributes() {
  *
  * @param string[] $extra_attributes Optional. Array of extra attributes to render on the block wrapper.
  * @return string String of HTML attributes.
+ *
+ * @phpstan-return ( $extra_attributes is empty ? string : non-falsy-string )
  */
 function get_block_wrapper_attributes( $extra_attributes = array() ) {
 	$new_attributes = WP_Block_Supports::get_instance()->apply_block_supports();
diff --git a/src/wp-includes/class-wp-dependencies.php b/src/wp-includes/class-wp-dependencies.php
index c2daba389bd75..167dfd692ef70 100644
--- a/src/wp-includes/class-wp-dependencies.php
+++ b/src/wp-includes/class-wp-dependencies.php
@@ -472,6 +472,16 @@ protected function recurse_deps( $queue, $handle ) {
 	 * @param string $handle Name of the item. Should be unique.
 	 * @param string $status Optional. Status of the item to query. Default 'registered'.
 	 * @return bool|_WP_Dependency Found, or object Item data.
+	 *
+	 * @phpstan-return (
+	 *     $handle is not non-empty-string
+	 *         ? false
+	 *         : (
+	 *             $status is not 'registered'|'scripts'|'enqueued'|'queued'|'to_do'|'to_print'|'done'|'printed'
+	 *                 ? false
+	 *                 : ( $status is 'registered'|'scripts' ? _WP_Dependency|false : bool )
+	 *         )
+	 * )
 	 */
 	public function query( $handle, $status = 'registered' ) {
 		switch ( $status ) {
diff --git a/src/wp-includes/comment.php b/src/wp-includes/comment.php
index f1ea45c5cd202..239435dc308a3 100644
--- a/src/wp-includes/comment.php
+++ b/src/wp-includes/comment.php
@@ -2809,6 +2809,8 @@ function wp_send_note_notification( WP_User $user, WP_Comment $comment, ?WP_Post
  * @param string         $comment_status New comment status, either 'hold', 'approve', 'spam', or 'trash'.
  * @param bool           $wp_error       Whether to return a WP_Error object if there is a failure. Default false.
  * @return bool|WP_Error True on success, false or WP_Error on failure.
+ *
+ * @phpstan-return ( $wp_error is false ? bool : true|WP_Error )
  */
 function wp_set_comment_status( $comment_id, $comment_status, $wp_error = false ) {
 	global $wpdb;
@@ -2883,6 +2885,8 @@ function wp_set_comment_status( $comment_id, $comment_status, $wp_error = false
  * @param bool  $wp_error   Optional. Whether to return a WP_Error on failure. Default false.
  * @return int|false|WP_Error The value 1 if the comment was updated, 0 if not updated.
  *                            False or a WP_Error object on failure.
+ *
+ * @phpstan-return ( $wp_error is false ? int|false : int|WP_Error )
  */
 function wp_update_comment( $commentarr, $wp_error = false ) {
 	global $wpdb;
diff --git a/src/wp-includes/cron.php b/src/wp-includes/cron.php
index 1070ae4680b91..968e30d25008b 100644
--- a/src/wp-includes/cron.php
+++ b/src/wp-includes/cron.php
@@ -44,6 +44,8 @@
  *                           database performance issues.
  * @param bool   $wp_error   Optional. Whether to return a WP_Error on failure. Default false.
  * @return bool|WP_Error True if event successfully scheduled. False or WP_Error on failure.
+ *
+ * @phpstan-return ( $wp_error is false ? bool : true|WP_Error )
  */
 function wp_schedule_single_event( $timestamp, $hook, $args = array(), $wp_error = false ) {
 	// Make sure timestamp is a positive integer.
@@ -248,6 +250,8 @@ function wp_schedule_single_event( $timestamp, $hook, $args = array(), $wp_error
  *                           database performance issues.
  * @param bool   $wp_error   Optional. Whether to return a WP_Error on failure. Default false.
  * @return bool|WP_Error True if event successfully scheduled. False or WP_Error on failure.
+ *
+ * @phpstan-return ( $wp_error is false ? bool : true|WP_Error )
  */
 function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array(), $wp_error = false ) {
 	// Make sure timestamp is a positive integer.
@@ -363,6 +367,8 @@ function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array(), $wp
  *                           database performance issues.
  * @param bool   $wp_error   Optional. Whether to return a WP_Error on failure. Default false.
  * @return bool|WP_Error True if event successfully rescheduled. False or WP_Error on failure.
+ *
+ * @phpstan-return ( $wp_error is false ? bool : true|WP_Error )
  */
 function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $wp_error = false ) {
 	// Make sure timestamp is a positive integer.
@@ -485,6 +491,8 @@ function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $
  *                          arguments do not match exactly, the event will not be found. Default empty array.
  * @param bool   $wp_error  Optional. Whether to return a WP_Error on failure. Default false.
  * @return bool|WP_Error True if event successfully unscheduled. False or WP_Error on failure.
+ *
+ * @phpstan-return ( $wp_error is false ? bool : true|WP_Error )
  */
 function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = false ) {
 	// Make sure timestamp is a positive integer.
@@ -572,6 +580,8 @@ function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = fa
  * @return int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no
  *                            events were registered with the hook and arguments combination), false or WP_Error
  *                            if unscheduling one or more events fail.
+ *
+ * @phpstan-return ( int<0, max>|( $wp_error is false ? false : WP_Error ) )
  */
 function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
 	/*
@@ -677,6 +687,8 @@ function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
  * @param bool   $wp_error Optional. Whether to return a WP_Error on failure. Default false.
  * @return int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no
  *                            events were registered on the hook), false or WP_Error if unscheduling fails.
+ *
+ * @phpstan-return ( $wp_error is false ? int<0, max>|false : int<0, max>|WP_Error )
  */
 function wp_unschedule_hook( $hook, $wp_error = false ) {
 	/**
diff --git a/src/wp-includes/deprecated.php b/src/wp-includes/deprecated.php
index 13c4f95f403d0..a8b03041ebdb8 100644
--- a/src/wp-includes/deprecated.php
+++ b/src/wp-includes/deprecated.php
@@ -2518,6 +2518,16 @@ function is_taxonomy( $taxonomy ) {
  * @param string $taxonomy The taxonomy name to use
  * @param int $parent ID of parent term under which to confine the exists search.
  * @return mixed Get the term ID or term object, if exists.
+ *
+ * @phpstan-return (
+ *     $term is 0
+ *         ? 0
+ *         : (
+ *             $term is ''
+ *                 ? null
+ *                 : ( $taxonomy is '' ? string|null : array{ term_id: string, term_taxonomy_id: string }|null )
+ *         )
+ * )
  */
 function is_term( $term, $taxonomy = '', $parent = 0 ) {
 	_deprecated_function( __FUNCTION__, '3.0.0', 'term_exists()' );
@@ -6505,6 +6515,8 @@ function wp_print_auto_sizes_contain_css_fix() {
  *
  * @param string|array $gpc String or array of data to slash.
  * @return string|array Slashed `$gpc`.
+ *
+ * @phpstan-return ( $gpc is string ? string : array )
  */
 function addslashes_gpc( $gpc ) {
 	_deprecated_function( __FUNCTION__, '7.0.0', 'wp_slash()' );
diff --git a/src/wp-includes/formatting.php b/src/wp-includes/formatting.php
index 5bf001c430a49..f99264bb8b092 100644
--- a/src/wp-includes/formatting.php
+++ b/src/wp-includes/formatting.php
@@ -2412,6 +2412,10 @@ function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'displa
  *
  * @param string $orderby Order by clause to be validated.
  * @return string|false Returns $orderby if valid, false otherwise.
+ *
+ * @phpstan-template T of string
+ * @phpstan-param T $orderby
+ * @phpstan-return ( T is non-falsy-string ? T|false : false )
  */
 function sanitize_sql_orderby( $orderby ) {
 	if ( preg_match( '/^\s*(([a-z0-9_]+|`[a-z0-9_]+`)(\s+(ASC|DESC))?\s*(,\s*(?=[a-z0-9_`])|$))+$/i', $orderby ) || preg_match( '/^\s*RAND\(\s*\)\s*$/i', $orderby ) ) {
@@ -2788,6 +2792,16 @@ function format_to_edit( $content, $rich_text = false ) {
  * @param int $number     Number to append zeros to if not greater than threshold.
  * @param int $threshold  Digit places number needs to be to not have zeros added.
  * @return string Adds leading zeros to number if needed.
+ *
+ * @phpstan-return (
+ *     $threshold is 0
+ *         ? lowercase-string&non-empty-string&numeric-string
+ *         : (
+ *             $number is int<0, max>
+ *                 ? lowercase-string&non-empty-string&numeric-string
+ *                 : lowercase-string&non-empty-string
+ *         )
+ * )
  */
 function zeroise( $number, $threshold ) {
 	return sprintf( '%0' . $threshold . 's', $number );
diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index 5dd1916737796..899d77903c9c1 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -469,6 +469,8 @@ function number_format_i18n( $number, $decimals = 0 ) {
  * @return string|false Number string on success, false on failure.
  *
  * @phpstan-param int|float|numeric-string $bytes
+ *
+ * @phpstan-return ( $bytes is int<0, max> ? string : string|false )
  */
 function size_format( $bytes, $decimals = 0 ) {
 	if ( ! is_numeric( $bytes ) ) {
@@ -636,6 +638,10 @@ function get_weekstartend( $mysqlstring, $start_of_week = '' ) {
  *
  * @param string|array|object $data Data that might be serialized.
  * @return mixed A scalar data.
+ *
+ * @phpstan-template T of mixed
+ * @phpstan-param T $data
+ * @phpstan-return ( T is array|object|string ? string : T )
  */
 function maybe_serialize( $data ) {
 	if ( is_array( $data ) || is_object( $data ) ) {
@@ -844,6 +850,8 @@ function xmlrpc_removepostdata( $content ) {
  *
  * @param string $content Content to extract URLs from.
  * @return string[] Array of URLs found in passed string.
+ *
+ * @phpstan-return ( $content is empty ? array{ } : list<string> )
  */
 function wp_extract_urls( $content ) {
 	preg_match_all(
@@ -1604,6 +1612,8 @@ function get_num_queries() {
  *
  * @param string $yn Character string containing either 'y' (yes) or 'n' (no).
  * @return bool True if 'y', false on anything else.
+ *
+ * @phpstan-return ( $yn is 'y' ? true : false )
  */
 function bool_from_yn( $yn ) {
 	return ( 'y' === strtolower( $yn ) );
@@ -2135,6 +2145,8 @@ function wp_mkdir_p( $target ) {
  *
  * @param string $path File path.
  * @return bool True if path is absolute, false is not absolute.
+ *
+ * @phpstan-return ( $path is non-falsy-string ? bool : false )
  */
 function path_is_absolute( $path ) {
 	/*
@@ -5420,6 +5432,8 @@ function _wp_to_kebab_case( $input_string ) {
  * @return bool Whether the variable is a list.
  *
  * @phpstan-assert-if-true array<int, mixed> $data
+ *
+ * @phpstan-return ( $data is array<int, mixed> ? true : false )
  */
 function wp_is_numeric_array( $data ): bool {
 	if ( ! is_array( $data ) ) {
@@ -6420,6 +6434,8 @@ function iis7_supports_permalinks() {
  * @param string   $file          File path.
  * @param string[] $allowed_files Optional. Array of allowed files. Default empty array.
  * @return int 0 means nothing is wrong, greater than 0 means something was wrong.
+ *
+ * @phpstan-return ( $file is '' ? 0 : ( $allowed_files is empty ? 0|1|2 : 0|1|2|3 ) )
  */
 function validate_file( $file, $allowed_files = array() ) {
 	if ( ! is_scalar( $file ) || '' === $file ) {
@@ -7434,6 +7450,8 @@ function wp_allowed_protocols() {
  *                             the raw array returned. Default true.
  * @return string|array Either a string containing a reversed comma separated trace or an array
  *                      of individual calls.
+ *
+ * @phpstan-return ( $pretty is true ? string : list<string> )
  */
 function wp_debug_backtrace_summary( $ignore_class = null, $skip_frames = 0, $pretty = true ) {
 	static $truncate_paths;
@@ -7743,6 +7761,8 @@ function wp_auth_check( $response ) {
  *
  * @param string $tag An HTML tag name. Example: 'video'.
  * @return string Tag RegEx.
+ *
+ * @phpstan-return ( $tag is ''|'0' ? '' : non-falsy-string )
  */
 function get_tag_regex( $tag ) {
 	if ( empty( $tag ) ) {
@@ -8189,6 +8209,8 @@ function wp_generate_uuid4() {
  * @param int   $version Specify which version of UUID to check against. Default is none,
  *                       to accept any UUID version. Otherwise, only version allowed is `4`.
  * @return bool The string is a valid UUID or false on failure.
+ *
+ * @phpstan-return ( $version is 4|null ? bool : false )
  */
 function wp_is_uuid( $uuid, $version = null ) {
 
@@ -8240,6 +8262,12 @@ function wp_unique_id( $prefix = '' ) {
  *
  * @param string $prefix Optional. Prefix for the returned ID. Default empty string.
  * @return string Incremental ID per prefix.
+ *
+ * @phpstan-return (
+ *     ( $prefix is ''|numeric-string ? numeric-string : string )
+ *     & non-falsy-string
+ *     & ( $prefix is lowercase-string ? lowercase-string : string )
+ * )
  */
 function wp_unique_prefixed_id( $prefix = '' ) {
 	static $id_counters = array();
diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php
index d6cf186ea4c93..71c234df6612d 100644
--- a/src/wp-includes/general-template.php
+++ b/src/wp-includes/general-template.php
@@ -4958,6 +4958,12 @@ function language_attributes( $doctype = 'html' ) {
  * }
  * @return string|string[]|null String of page links or array of page links, depending on 'type' argument.
  *                              Null if total number of pages is less than 2.
+ *
+ * @phpstan-return (
+ *     $args is array{ total: int<min, 1>, ... }
+ *         ? null
+ *         : ( $args is array{ type: 'array', ... } ? list<string> : string )
+ * )
  */
 function paginate_links( $args = '' ) {
 	global $wp_query, $wp_rewrite;
diff --git a/src/wp-includes/http.php b/src/wp-includes/http.php
index c2855a8d8d9c1..f46e6f4658c20 100644
--- a/src/wp-includes/http.php
+++ b/src/wp-includes/http.php
@@ -555,6 +555,10 @@ function send_origin_headers() {
  *
  * @param string $url Request URL.
  * @return string|false Returns false if the URL is not safe, or the original URL if it is safe.
+ *
+ * @phpstan-template TUrl of string
+ * @phpstan-param TUrl $url
+ * @phpstan-return ( TUrl is numeric|'' ? false : TUrl|false )
  */
 function wp_http_validate_url( $url ) {
 	if ( ! is_string( $url ) || '' === $url || is_numeric( $url ) ) {
diff --git a/src/wp-includes/l10n/class-wp-translations.php b/src/wp-includes/l10n/class-wp-translations.php
index e919fea8b94b3..f516bd1c7665d 100644
--- a/src/wp-includes/l10n/class-wp-translations.php
+++ b/src/wp-includes/l10n/class-wp-translations.php
@@ -112,6 +112,10 @@ private function make_entry( $original, $translations ): Translation_Entry {
 	 * @param int|float   $count    Count. Should be an integer, but some plugins pass floats.
 	 * @param string|null $context  Context.
 	 * @return string|null Translation if it exists, or the unchanged singular string.
+	 *
+	 * @phpstan-template T of string|null
+	 * @phpstan-param T $singular
+	 * @phpstan-return ( $singular is null ? null : ( $plural is null ? T : string ) )
 	 */
 	public function translate_plural( $singular, $plural, $count = 1, $context = '' ) {
 		if ( null === $singular || null === $plural ) {
diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php
index 10bda681154f9..af023cf1e87c3 100644
--- a/src/wp-includes/link-template.php
+++ b/src/wp-includes/link-template.php
@@ -153,6 +153,8 @@ function wp_force_plain_post_permalink( $post = null, $sample = null ) {
  * @param int|WP_Post $post      Optional. Post ID or post object. Default is the global `$post`.
  * @param bool        $leavename Optional. Whether to keep post name or page name. Default false.
  * @return string|false The permalink URL. False if the post does not exist.
+ *
+ * @phpstan-return ( $post is WP_Post ? string : string|false )
  */
 function get_the_permalink( $post = 0, $leavename = false ) {
 	return get_permalink( $post, $leavename );
@@ -320,6 +322,8 @@ function get_permalink( $post = 0, $leavename = false ) {
  * @param bool        $leavename Optional. Whether to keep post name. Default false.
  * @param bool        $sample    Optional. Is it a sample permalink. Default false.
  * @return string|false The post permalink URL. False if the post does not exist.
+ *
+ * @phpstan-return ( $post is WP_Post ? string : string|false )
  */
 function get_post_permalink( $post = 0, $leavename = false, $sample = false ) {
 	global $wp_rewrite;
diff --git a/src/wp-includes/load.php b/src/wp-includes/load.php
index 061754e8b4e52..1558a44189226 100644
--- a/src/wp-includes/load.php
+++ b/src/wp-includes/load.php
@@ -1832,6 +1832,8 @@ function wp_doing_cron() {
  * @return bool Whether the variable is an instance of WP_Error.
  *
  * @phpstan-assert-if-true WP_Error $thing
+ *
+ * @phpstan-return ( $thing is WP_Error ? true : false )
  */
 function is_wp_error( $thing ) {
 	$is_wp_error = ( $thing instanceof WP_Error );
diff --git a/src/wp-includes/pluggable.php b/src/wp-includes/pluggable.php
index aa39c31d78ce5..ff5a4d5da5621 100644
--- a/src/wp-includes/pluggable.php
+++ b/src/wp-includes/pluggable.php
@@ -97,6 +97,12 @@ function get_userdata( $user_id ) {
 	 * @param string     $field The field to retrieve the user with. id | ID | slug | email | login.
 	 * @param int|string $value A value for $field. A user ID, slug, email address, or login name.
 	 * @return WP_User|false WP_User object on success, false on failure.
+	 *
+	 * @phpstan-return (
+	 *     $field is 'id'|'ID'
+	 *         ? ( $value is int<min, 0> ? false : WP_User|false )
+	 *         : WP_User|false
+	 * )
 	 */
 	function get_user_by( $field, $value ) {
 		$userdata = WP_User::get_data_by( $field, $value );
diff --git a/src/wp-includes/rest-api.php b/src/wp-includes/rest-api.php
index c1462890213e5..f3dad2ff1f0bf 100644
--- a/src/wp-includes/rest-api.php
+++ b/src/wp-includes/rest-api.php
@@ -694,6 +694,8 @@ function rest_ensure_request( $request ) {
  * @return WP_REST_Response|WP_Error If response generated an error, WP_Error, if response
  *                                   is already an instance, WP_REST_Response, otherwise
  *                                   returns a new WP_REST_Response instance.
+ *
+ * @phpstan-return ( $response is WP_Error ? WP_Error : WP_REST_Response )
  */
 function rest_ensure_response( $response ) {
 	if ( is_wp_error( $response ) ) {
@@ -1531,6 +1533,10 @@ function rest_is_ip_address( $ip ) {
  *
  * @param bool|string|int $value The value being evaluated.
  * @return bool Returns the proper associated boolean value.
+ *
+ * @phpstan-template T of bool|string|int
+ * @phpstan-param T $value
+ * @phpstan-return ( T is bool ? T : ( T is ''|'false'|'FALSE'|'0'|0 ? false : true ) )
  */
 function rest_sanitize_boolean( $value ) {
 	// String values are translated to `true`; make sure 'false' is false.
diff --git a/src/wp-includes/revision.php b/src/wp-includes/revision.php
index 6e27fad4fa0a4..e562cd0cd5167 100644
--- a/src/wp-includes/revision.php
+++ b/src/wp-includes/revision.php
@@ -307,6 +307,12 @@ function wp_get_post_autosave( $post_id, $user_id = 0 ) {
  *
  * @param int|WP_Post $post Post ID or post object.
  * @return int|false ID of revision's parent on success, false if not a revision.
+ *
+ * @phpstan-return (
+ *     $post is WP_Post
+ *         ? false|int<0, max>
+ *         : ( $post is int<min, 0> ? false : false|int<0, max> )
+ * )
  */
 function wp_is_post_revision( $post ) {
 	$post = wp_get_post_revision( $post );
diff --git a/src/wp-includes/shortcodes.php b/src/wp-includes/shortcodes.php
index 01fed7244e548..1ba655b176733 100644
--- a/src/wp-includes/shortcodes.php
+++ b/src/wp-includes/shortcodes.php
@@ -145,6 +145,8 @@ function shortcode_exists( $tag ) {
  * @param string $content Content to search for shortcodes.
  * @param string $tag     Shortcode tag to check.
  * @return bool Whether the passed content contains the given shortcode.
+ *
+ * @phpstan-return ( $tag is empty ? false : ( $content is empty ? false : bool ) )
  */
 function has_shortcode( $content, $tag ) {
 	if ( ! str_contains( $content, '[' ) ) {
diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php
index 52e6b99b7b802..ec24ca2ca496b 100644
--- a/src/wp-includes/taxonomy.php
+++ b/src/wp-includes/taxonomy.php
@@ -374,6 +374,8 @@ function get_taxonomy( $taxonomy ) {
  *
  * @param string $taxonomy Name of taxonomy object.
  * @return bool Whether the taxonomy exists.
+ *
+ * @phpstan-return ( $taxonomy is non-falsy-string ? bool : false )
  */
 function taxonomy_exists( $taxonomy ) {
 	global $wp_taxonomies;
@@ -1836,6 +1838,14 @@ function sanitize_term( $term, $taxonomy, $context = 'display' ) {
  *                         Accepts 'raw', 'edit', 'db', 'display', 'rss',
  *                         'attribute', or 'js'.
  * @return mixed Sanitized field.
+ *
+ * @phpstan-template T of string
+ * @phpstan-param T $value
+ * @phpstan-return (
+ *     $field is 'parent'|'term_id'|'count'|'term_group'|'term_taxonomy_id'|'object_id'
+ *         ? int<0, max>
+ *         : ( $context is 'raw' ? T : ( $context is 'attribute'|'edit'|'js' ? string : mixed ) )
+ * )
  */
 function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) {
 	$int_fields = array( 'parent', 'term_id', 'count', 'term_group', 'term_taxonomy_id', 'object_id' );
diff --git a/src/wp-includes/user.php b/src/wp-includes/user.php
index c26d88912c8b2..2cea28357b0d1 100644
--- a/src/wp-includes/user.php
+++ b/src/wp-includes/user.php
@@ -854,6 +854,8 @@ function delete_user_option( $user_id, $option_name, $is_global = false ) {
  *
  * @param int $user_id User ID.
  * @return WP_User|false WP_User object on success, false on failure.
+ *
+ * @phpstan-return ( $user_id is int<min, 0> ? false : WP_User|false )
  */
 function get_user( $user_id ) {
 	return get_user_by( 'id', $user_id );
diff --git a/tests/phpstan/baselines/if.alwaysFalse.neon b/tests/phpstan/baselines/if.alwaysFalse.neon
index 6e33ed2a5365c..cc72813ceafbc 100644
--- a/tests/phpstan/baselines/if.alwaysFalse.neon
+++ b/tests/phpstan/baselines/if.alwaysFalse.neon
@@ -28,11 +28,6 @@ parameters:
 			identifier: if.alwaysFalse
 			count: 2
 			path: ../../../src/wp-includes/class-wp-block-processor.php
-		-
-			message: '#^If condition is always false\.$#'
-			identifier: if.alwaysFalse
-			count: 1
-			path: ../../../src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php
 		-
 			message: '#^If condition is always false\.$#'
 			identifier: if.alwaysFalse

From a3fbdcf22d54f1871a23292c21915b90d35e5195 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 20:47:51 -0700
Subject: [PATCH 14/18] Adopt the stubs' `get_bookmark()` conditional, and
 revive `get_link()` with it.

Of the twelve conditional return types in
https://github.com/WordPress/wordpress-develop/pull/13530 that overlap work
already on this branch, `get_bookmark()` is the one where that PR is plainly
ahead, and it unblocks a function dropped earlier for want of exactly this.

`get_bookmark()` was attempted here before and abandoned: `sanitize_bookmark()`
declares `stdClass|array` and `$_bookmark` is `mixed` for much of the function, so
a `stdClass` branch produced errors on the returns. The version in that PR gets
around it by spelling the array branches `array<string, mixed>` and
`array<int, mixed>`, whose union is plain `array` and therefore accepts whatever
`sanitize_bookmark()` hands back. The earlier attempt here used `list<mixed>` for
the `ARRAY_N` branch, which is more precise and breaks that union. Precision was
the wrong trade: this removes two errors, one of them the missing value type on the
`@return`.

`get_link()` is the deprecated wrapper over `get_bookmark()` and was dropped for
the same reason, so give it the same condition. Its `@return` also gains the `null`
it has always been able to return.

The other eleven overlaps stay as they are:

- `mysql2date()`, `current_time()`, `single_month_title()` and `get_sites()` are
  the same type either way; the two branches converged on them independently.
- `get_term()` and `get_term_by()` are written there with `array<string, string|int>`
  and `list<string|int>` rather than `mixed`. More precise and not checkable:
  `WP_Term::to_array()` returns `array<string, mixed>`, and tightening that runs
  into `get_object_vars()`, which PHPStan will not resolve to a shape. Adopting it
  costs two `return.type` errors for no gain.
- `get_category()` is written there as an intersection of two conditionals, one on
  `$output` and one on `$category`, which is a technique worth knowing and narrows
  better. The `$category` half is wrong, though: it excludes `WP_Error|null` for any
  object, while a `stdClass` whose `filter` is set to anything but 'raw' reaches
  `WP_Term::get_instance()`, which is documented `WP_Term|WP_Error|false`. Nothing
  in core passes an object to `get_category()` anyway.
- `get_category_by_path()` differs only in `array<int, mixed>` where this branch has
  the more precise `list<mixed>`, which verifies here.
- `wp_insert_category()` is written there as `int<0, max>` and `int<1, max>|WP_Error`.
  Correct, and it does not verify: the term ID comes back from `wp_insert_term()` and
  `wp_update_term()` as a plain `int`, and that PR does not retype either.
- `has_filter()` and `has_action()` are written there without the `$priority`
  parameter added in 6.9.0, so they report `false|int` for a call that passes a
  priority, where the function returns a bool.

A `property.nonObject` baseline entry falls away, now that `get_bookmark()` reports
an object rather than `mixed`.

Verified against `phpstan.neon.dist` with PHPStan running on PHP 8.2.33 and 8.3.33:
no errors on either.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/bookmark.php                    |  7 +++++++
 src/wp-includes/deprecated.php                  | 10 +++++++++-
 tests/phpstan/baselines/property.nonObject.neon |  5 -----
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/wp-includes/bookmark.php b/src/wp-includes/bookmark.php
index 9e44d781909ed..e1c8a6e522a00 100644
--- a/src/wp-includes/bookmark.php
+++ b/src/wp-includes/bookmark.php
@@ -20,6 +20,13 @@
  *                               respectively. Default OBJECT.
  * @param string       $filter   Optional. How to sanitize bookmark fields. Default 'raw'.
  * @return array|object|null Type returned depends on $output value.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-return null|(
+ *     $output is 'ARRAY_A' ? array<string, mixed> : (
+ *         $output is 'ARRAY_N' ? array<int, mixed> : stdClass
+ *     )
+ * )
  */
 function get_bookmark( $bookmark, $output = OBJECT, $filter = 'raw' ) {
 	global $wpdb;
diff --git a/src/wp-includes/deprecated.php b/src/wp-includes/deprecated.php
index a8b03041ebdb8..75d064c414ee2 100644
--- a/src/wp-includes/deprecated.php
+++ b/src/wp-includes/deprecated.php
@@ -2021,7 +2021,15 @@ function get_attachment_innerHTML($id = 0, $fullsize = false, $max_dims = false)
  *                            Default OBJECT.
  * @param string $filter      Optional. How to filter the link for output. Accepts 'raw', 'edit',
  *                            'attribute', 'js', 'db', or 'display'. Default 'raw'.
- * @return object|array Bookmark object or array, depending on the type specified by `$output`.
+ * @return object|array|null Bookmark object or array, depending on the type specified by `$output`.
+ *                            Null if the bookmark does not exist.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-return null|(
+ *     $output is 'ARRAY_A' ? array<string, mixed> : (
+ *         $output is 'ARRAY_N' ? array<int, mixed> : stdClass
+ *     )
+ * )
  */
 function get_link( $bookmark_id, $output = OBJECT, $filter = 'raw' ) {
 	_deprecated_function( __FUNCTION__, '2.1.0', 'get_bookmark()' );
diff --git a/tests/phpstan/baselines/property.nonObject.neon b/tests/phpstan/baselines/property.nonObject.neon
index b996081f9b11b..895c9e3656d3d 100644
--- a/tests/phpstan/baselines/property.nonObject.neon
+++ b/tests/phpstan/baselines/property.nonObject.neon
@@ -188,11 +188,6 @@ parameters:
 			identifier: property.nonObject
 			count: 1
 			path: ../../../src/wp-includes/customize/class-wp-customize-nav-menu-control.php
-		-
-			message: '#^Cannot access property \$link_id on array\|object\.$#'
-			identifier: property.nonObject
-			count: 3
-			path: ../../../src/wp-includes/link-template.php
 		-
 			message: '#^Cannot access property \$plugins on array\|object\.$#'
 			identifier: property.nonObject

From 98f5f283a5b4c7dff189c8a37002843db40bdf6b Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Fri, 18 Sep 2026 20:58:22 -0700
Subject: [PATCH 15/18] Add the remaining conditional return types from the
 stubs' function map.

Eight of the conditional types in
https://github.com/WordPress/wordpress-develop/pull/13530 did not go in with the
rest. Six do now, and the two that do not are recorded below.

`WP_Theme::offsetExists()` and `WP_Theme::offsetGet()` answer for a fixed set of
header names, so both condition on whether `$offset` is one of them. The set is
declared once as a `@phpstan-type Theme_Key` on the class, which is what the two
conditions are written in terms of; that PR calls it `ThemeKey`, but core's own
aliases are `Data_Array`, `Endpoint_Arg`, `Header_Image_Data` and so on, so follow
that. Array access resolves through the condition: `$theme['Bogus']` is now `null`
rather than `mixed`. `isset( $theme['Name'] )` still does not, because PHPStan
answers that from its own ArrayAccess handling rather than from `offsetExists()`,
but a direct call does.

`wp_unique_id()` and `wp_unique_id_from_values()` return a string whose shape
follows the prefix: lowercase for a lowercase prefix, and numeric when there is no
prefix at all. `WP_Translations::translate()` returns null only for a null
singular. `get_permalink()` cannot fail when handed a `WP_Post` rather than an ID,
so the `false` drops out for that case.

`absint()` keeps the `non-negative-int` it already had. The version in that PR
resolves literals exactly -- `absint( 5 )` to `5`, `absint( 'abc' )` to `0`,
`absint( true )` to `1` -- but it costs more than it returns. It gives up the
non-negative guarantee for any argument PHPStan cannot pin down, which is most of
them, resolving `absint( $mixed )` to plain `int`; and the template it uses needs a
`@phpstan-param T|scalar|array|resource|null`, which narrows a parameter that was
`mixed` and so reports at every call site handing it something unknown. Measured
across the whole tree that is 215 errors added against a handful resolved. Stating
the guarantee unconditionally in one line is the better trade. Intersecting the two
was tried and does not work either: the intersection stops the template resolving,
so the literal precision is lost anyway.

`_get_list_table()` keeps what it has too. It is already generic, taking
`class-string<T>` and returning `T|false`, which holds for any class name. The
version in that PR enumerates the seventeen core list tables and returns `new<T>`,
which is more precise for those and says nothing about anything else.

Verified against `phpstan.neon.dist` with PHPStan running on PHP 8.2.33 and
8.3.33: no errors on either, and no baseline needed regenerating.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/class-wp-theme.php             | 6 ++++++
 src/wp-includes/functions.php                  | 8 ++++++++
 src/wp-includes/l10n/class-wp-translations.php | 2 ++
 src/wp-includes/link-template.php              | 2 ++
 4 files changed, 18 insertions(+)

diff --git a/src/wp-includes/class-wp-theme.php b/src/wp-includes/class-wp-theme.php
index 2335918979a8a..87fcd7eec72b4 100644
--- a/src/wp-includes/class-wp-theme.php
+++ b/src/wp-includes/class-wp-theme.php
@@ -5,6 +5,8 @@
  * @package WordPress
  * @subpackage Theme
  * @since 3.4.0
+ *
+ * @phpstan-type Theme_Key 'Name'|'Version'|'Status'|'Title'|'Author'|'Author Name'|'Author URI'|'Description'|'Template'|'Stylesheet'|'Template Files'|'Stylesheet Files'|'Template Dir'|'Stylesheet Dir'|'Screenshot'|'Tags'|'Theme Root'|'Theme Root URI'|'Parent Theme'
  */
 #[AllowDynamicProperties]
 final class WP_Theme implements ArrayAccess {
@@ -654,6 +656,8 @@ public function offsetUnset( $offset ) {}
 	 *
 	 * @param mixed $offset
 	 * @return bool
+	 *
+	 * @phpstan-return ( $offset is Theme_Key ? true : false )
 	 */
 	#[ReturnTypeWillChange]
 	public function offsetExists( $offset ) {
@@ -696,6 +700,8 @@ public function offsetExists( $offset ) {
 	 *
 	 * @param mixed $offset
 	 * @return mixed
+	 *
+	 * @phpstan-return ( $offset is Theme_Key ? mixed : null )
 	 */
 	#[ReturnTypeWillChange]
 	public function offsetGet( $offset ) {
diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index 899d77903c9c1..bab7cf8267f02 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -8243,6 +8243,12 @@ function wp_is_uuid( $uuid, $version = null ) {
  *
  * @param string $prefix Prefix for the returned ID.
  * @return string Unique ID.
+ *
+ * @phpstan-return (
+ *     ( $prefix is ''|numeric-string ? numeric-string : string )
+ *     & non-falsy-string
+ *     & ( $prefix is lowercase-string ? lowercase-string : string )
+ * )
  */
 function wp_unique_id( $prefix = '' ) {
 	static $id_counter = 0;
@@ -8301,6 +8307,8 @@ function wp_unique_prefixed_id( $prefix = '' ) {
  * @param array  $data   The input array to generate an ID from.
  * @param string $prefix Optional. A prefix to prepend to the generated ID. Default empty string.
  * @return string The generated unique ID for the array.
+ *
+ * @phpstan-return ( $prefix is lowercase-string ? lowercase-string&non-falsy-string : non-falsy-string )
  */
 function wp_unique_id_from_values( array $data, string $prefix = '' ): string {
 	if ( empty( $data ) ) {
diff --git a/src/wp-includes/l10n/class-wp-translations.php b/src/wp-includes/l10n/class-wp-translations.php
index f516bd1c7665d..2cccf542d8b3b 100644
--- a/src/wp-includes/l10n/class-wp-translations.php
+++ b/src/wp-includes/l10n/class-wp-translations.php
@@ -139,6 +139,8 @@ public function translate_plural( $singular, $plural, $count = 1, $context = ''
 	 * @param string|null $singular Singular string.
 	 * @param string|null $context  Context.
 	 * @return string|null Translation if it exists, or the unchanged singular string
+	 *
+	 * @phpstan-return ( $singular is null ? null : string )
 	 */
 	public function translate( $singular, $context = '' ) {
 		if ( null === $singular ) {
diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php
index af023cf1e87c3..3d4ffc23b8f62 100644
--- a/src/wp-includes/link-template.php
+++ b/src/wp-includes/link-template.php
@@ -168,6 +168,8 @@ function get_the_permalink( $post = 0, $leavename = false ) {
  * @param int|WP_Post $post      Optional. Post ID or post object. Default is the global `$post`.
  * @param bool        $leavename Optional. Whether to keep post name or page name. Default false.
  * @return string|false The permalink URL. False if the post does not exist.
+ *
+ * @phpstan-return ( $post is WP_Post ? string : string|false )
  */
 function get_permalink( $post = 0, $leavename = false ) {
 	$rewritecode = array(

From 9e7fb8b342948c2d36f90f4129a1542b14511078 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Sun, 20 Sep 2026 16:30:54 -0700
Subject: [PATCH 16/18] Write the empty array shape as `array{}`.

Two of the conditional return types taken from the stubs' function map came out as
`array{ }`. The spacing is an artifact of reformatting them to core's conventions:
the rule that puts a space inside an array shape, so that `array{count: true, ...}`
becomes `array{ count: true, ... }`, has nothing to sit between the braces when the
shape is empty and leaves a lone space there instead.

Core writes the empty shape closed up, in `get_approved_comments()` and in
`wp_get_scheduled_event()`, so match that.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-admin/includes/bookmark.php | 2 +-
 src/wp-includes/functions.php      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/wp-admin/includes/bookmark.php b/src/wp-admin/includes/bookmark.php
index 7fa308c93172a..40ecc83d2c7de 100644
--- a/src/wp-admin/includes/bookmark.php
+++ b/src/wp-admin/includes/bookmark.php
@@ -123,7 +123,7 @@ function wp_delete_link( $link_id ) {
  * @param int $link_id Link ID to look up.
  * @return int[] The IDs of the requested link's categories.
  *
- * @phpstan-return ( $link_id is empty ? array{ } : array<int, int<1, max>> )
+ * @phpstan-return ( $link_id is empty ? array{} : array<int, int<1, max>> )
  */
 function wp_get_link_cats( $link_id = 0 ) {
 	$cats = wp_get_object_terms( $link_id, 'link_category', array( 'fields' => 'ids' ) );
diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index bab7cf8267f02..e8932d383b503 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -851,7 +851,7 @@ function xmlrpc_removepostdata( $content ) {
  * @param string $content Content to extract URLs from.
  * @return string[] Array of URLs found in passed string.
  *
- * @phpstan-return ( $content is empty ? array{ } : list<string> )
+ * @phpstan-return ( $content is empty ? array{} : list<string> )
  */
 function wp_extract_urls( $content ) {
 	preg_match_all(

From c348216d01518354a1e6b4bc014780b391648b4d Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Sun, 20 Sep 2026 16:41:24 -0700
Subject: [PATCH 17/18] Correct return type of wp_get_link_cats() to account
 for WP_Error

---
 src/wp-admin/includes/bookmark.php | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/wp-admin/includes/bookmark.php b/src/wp-admin/includes/bookmark.php
index 40ecc83d2c7de..eefb05df464de 100644
--- a/src/wp-admin/includes/bookmark.php
+++ b/src/wp-admin/includes/bookmark.php
@@ -121,12 +121,13 @@ function wp_delete_link( $link_id ) {
  * @since 2.1.0
  *
  * @param int $link_id Link ID to look up.
- * @return int[] The IDs of the requested link's categories.
- *
- * @phpstan-return ( $link_id is empty ? array{} : array<int, int<1, max>> )
+ * @return int[]|WP_Error The IDs of the requested link's categories, or else a WP_Error if the `link_category` taxonomy was unregistered.
  */
 function wp_get_link_cats( $link_id = 0 ) {
 	$cats = wp_get_object_terms( $link_id, 'link_category', array( 'fields' => 'ids' ) );
+	if ( is_wp_error( $cats ) ) {
+		return $cats;
+	}
 	return array_unique( $cats );
 }
 

From 637431f821e6e5372ee3e12bb9dd19e6a639d932 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Mon, 21 Sep 2026 08:10:14 -0700
Subject: [PATCH 18/18] Widen five conditional return types that claimed more
 than core delivers.

Same class of problem as `wp_get_link_cats()`: a type taken from the stubs'
function map describes what the function ought to produce rather than what the
code and the surrounding annotations actually guarantee. None of these report at
rule level 5, so the tree stayed clean, but each one is an error waiting at a
higher level.

`wp_unschedule_hook()` and `wp_clear_scheduled_hook()` claimed `int<0, max>`. The
count is assembled from `count()` calls, but the `pre_unschedule_hook` and
`pre_clear_scheduled_hook` filters are documented as returning `null|int|false|WP_Error`
and are returned directly, so any int can come back. Widened to `int`.

`wp_http_validate_url()` was written with a template asserting that the argument
comes back unchanged. It does not: `$url` is reassigned from
`wp_kses_bad_protocol()` before any of the successful returns, so what is returned
is a sanitized string rather than the string passed in. Dropped the template and
kept the part that holds, which is that a numeric or empty URL yields false.

`sanitize_sql_orderby()` conditioned on `non-falsy-string`, which gets `'0'`
wrong. `'0'` matches the orderby pattern and is returned unchanged, so a falsy
string is a perfectly good result; the condition has to be `non-empty-string`.

`rest_sanitize_boolean()` used a template bound to `$value`, which narrowed a
parameter that was `mixed` and broke `rest_sanitize_value_from_schema()`, its only
caller in core, which passes a value of unknown type. Conditioned on the parameter
directly instead. The only thing given up is that a `true` argument no longer
resolves to `true` rather than `bool`.

Measured at rule level 10, where these were reported: seven errors resolved, in
`cron.php`, `http.php`, `formatting.php` and `rest-api.php`. Level 5 is unchanged
and still clean on PHP 8.2.33 and 8.3.33.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/wp-includes/cron.php       | 4 ++--
 src/wp-includes/formatting.php | 2 +-
 src/wp-includes/http.php       | 4 +---
 src/wp-includes/rest-api.php   | 4 +---
 4 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/src/wp-includes/cron.php b/src/wp-includes/cron.php
index 968e30d25008b..743b37b326b25 100644
--- a/src/wp-includes/cron.php
+++ b/src/wp-includes/cron.php
@@ -581,7 +581,7 @@ function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = fa
  *                            events were registered with the hook and arguments combination), false or WP_Error
  *                            if unscheduling one or more events fail.
  *
- * @phpstan-return ( int<0, max>|( $wp_error is false ? false : WP_Error ) )
+ * @phpstan-return ( int|( $wp_error is false ? false : WP_Error ) )
  */
 function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
 	/*
@@ -688,7 +688,7 @@ function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
  * @return int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no
  *                            events were registered on the hook), false or WP_Error if unscheduling fails.
  *
- * @phpstan-return ( $wp_error is false ? int<0, max>|false : int<0, max>|WP_Error )
+ * @phpstan-return ( $wp_error is false ? int|false : int|WP_Error )
  */
 function wp_unschedule_hook( $hook, $wp_error = false ) {
 	/**
diff --git a/src/wp-includes/formatting.php b/src/wp-includes/formatting.php
index f99264bb8b092..123885663ba85 100644
--- a/src/wp-includes/formatting.php
+++ b/src/wp-includes/formatting.php
@@ -2415,7 +2415,7 @@ function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'displa
  *
  * @phpstan-template T of string
  * @phpstan-param T $orderby
- * @phpstan-return ( T is non-falsy-string ? T|false : false )
+ * @phpstan-return ( T is non-empty-string ? T|false : false )
  */
 function sanitize_sql_orderby( $orderby ) {
 	if ( preg_match( '/^\s*(([a-z0-9_]+|`[a-z0-9_]+`)(\s+(ASC|DESC))?\s*(,\s*(?=[a-z0-9_`])|$))+$/i', $orderby ) || preg_match( '/^\s*RAND\(\s*\)\s*$/i', $orderby ) ) {
diff --git a/src/wp-includes/http.php b/src/wp-includes/http.php
index f46e6f4658c20..1a189a261306b 100644
--- a/src/wp-includes/http.php
+++ b/src/wp-includes/http.php
@@ -556,9 +556,7 @@ function send_origin_headers() {
  * @param string $url Request URL.
  * @return string|false Returns false if the URL is not safe, or the original URL if it is safe.
  *
- * @phpstan-template TUrl of string
- * @phpstan-param TUrl $url
- * @phpstan-return ( TUrl is numeric|'' ? false : TUrl|false )
+ * @phpstan-return ( $url is numeric|'' ? false : string|false )
  */
 function wp_http_validate_url( $url ) {
 	if ( ! is_string( $url ) || '' === $url || is_numeric( $url ) ) {
diff --git a/src/wp-includes/rest-api.php b/src/wp-includes/rest-api.php
index f3dad2ff1f0bf..5bc3c53c365c5 100644
--- a/src/wp-includes/rest-api.php
+++ b/src/wp-includes/rest-api.php
@@ -1534,9 +1534,7 @@ function rest_is_ip_address( $ip ) {
  * @param bool|string|int $value The value being evaluated.
  * @return bool Returns the proper associated boolean value.
  *
- * @phpstan-template T of bool|string|int
- * @phpstan-param T $value
- * @phpstan-return ( T is bool ? T : ( T is ''|'false'|'FALSE'|'0'|0 ? false : true ) )
+ * @phpstan-return ( $value is bool ? bool : ( $value is ''|'false'|'FALSE'|'0'|0 ? false : true ) )
  */
 function rest_sanitize_boolean( $value ) {
 	// String values are translated to `true`; make sure 'false' is false.