Code Quality: Declare conditional return types where an argument selects the return type.

src/wp-admin/includes/bookmark.php

@@ -121,10 +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.
+ * @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 );
 }
 
@@ -170,6 +173,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;

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 ) ) {

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 ) ) {

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(
@@ -218,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' );

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 ) {

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;

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;

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(

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' );
@@ -88,6 +106,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 +146,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 ) );
@@ -293,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' );
@@ -339,6 +385,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 );

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();

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 );

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 ) {

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
+	 *             : false|int )
+	 * )
 	 */
 	public function has_filter( $hook_name = '', $callback = false, $priority = false ) {
 		if ( false === $callback ) {

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 ) );
 

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 );

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 );