From cf68c9002141901671921f6fd5774aa98f341f3c Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 8 Jan 2021 15:22:17 +0000 Subject: [PATCH] Taxonomy: Correct and clarify documentation for the return types of term query functions. See #51800, #38266 git-svn-id: https://develop.svn.wordpress.org/trunk@49947 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/class-wp-term-query.php | 42 ++++++++++++++++++++--- src/wp-includes/taxonomy.php | 14 +++++--- tests/phpunit/tests/term/wpInsertTerm.php | 2 +- 3 files changed, 49 insertions(+), 9 deletions(-) diff --git a/src/wp-includes/class-wp-term-query.php b/src/wp-includes/class-wp-term-query.php index b507a0f874..0f679535c3 100644 --- a/src/wp-includes/class-wp-term-query.php +++ b/src/wp-includes/class-wp-term-query.php @@ -285,12 +285,16 @@ class WP_Term_Query { } /** - * Sets up the query for retrieving terms. + * Sets up the query and retrieves the results. + * + * The return type varies depending on the value passed to `$args['fields']`. See + * WP_Term_Query::get_terms() for details. * * @since 4.6.0 * * @param string|array $query Array or URL query string of parameters. - * @return array|int List of terms, or number of terms when 'count' is passed as a query var. + * @return WP_Term[]|int[]|string[]|string Array of terms, or number of terms as numeric string + * when 'count' is passed as a query var. */ public function query( $query ) { $this->query_vars = wp_parse_args( $query ); @@ -298,13 +302,43 @@ class WP_Term_Query { } /** - * Get terms, based on query_vars. + * Retrieves the query results. + * + * The return type varies depending on the value passed to `$args['fields']`. + * + * The following will result in an array of `WP_Term` objects being returned: + * + * - 'all' + * - 'all_with_object_id' + * + * The following will result in a numeric string being returned: + * + * - 'count' + * + * The following will result in an array of text strings being returned: + * + * - 'id=>name' + * - 'id=>slug' + * - 'names' + * - 'slugs' + * + * The following will result in an array of numeric strings being returned: + * + * - 'id=>parent' + * + * The following will result in an array of integers being returned: + * + * - 'ids' + * - 'tt_ids' + * + * In all cases, a `WP_Error` object will be returned if an invalid taxonomy is used. * * @since 4.6.0 * * @global wpdb $wpdb WordPress database abstraction object. * - * @return array List of terms. + * @return WP_Term[]|int[]|string[]|string Array of terms, or number of terms as numeric string + * when 'count' is passed as a query var. */ public function get_terms() { global $wpdb; diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php index 70f5d3bca8..5055b612c6 100644 --- a/src/wp-includes/taxonomy.php +++ b/src/wp-includes/taxonomy.php @@ -1131,11 +1131,15 @@ function get_term_to_edit( $id, $taxonomy ) { } /** - * Retrieve the terms in a given taxonomy or list of taxonomies. + * Retrieves the terms in a given taxonomy or list of taxonomies. * * You can fully inject any customizations to the query before it is sent, as * well as control the output with a filter. * + * The return type varies depending on the value passed to `$args['fields']`. See + * WP_Term_Query::get_terms() for details. In all cases, a `WP_Error` object will + * be returned if an invalid taxonomy is requested. + * * The {@see 'get_terms'} filter will be called when the cache has the term and will * pass the found term along with the array of $taxonomies and array of $args. * This filter is also called before the array of terms is passed and will pass @@ -1177,8 +1181,9 @@ function get_term_to_edit( $id, $taxonomy ) { * If present, this parameter will be interpreted as `$args`, and the first * function parameter will be parsed as a taxonomy or array of taxonomies. * Default empty. - * @return WP_Term[]|int|WP_Error Array of WP_Term instances, a count thereof, - * or WP_Error if any of the taxonomies do not exist. + * @return WP_Term[]|int[]|string[]|string|WP_Error Array of terms, a count thereof as a numeric string, + * or WP_Error if any of the taxonomies do not exist. + * See the function description for more information. */ function get_terms( $args = array(), $deprecated = '' ) { $term_query = new WP_Term_Query(); @@ -1745,7 +1750,8 @@ function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) { * If present, this parameter will be interpreted as `$args`, and the first * function parameter will be parsed as a taxonomy or array of taxonomies. * Default empty. - * @return array|int|WP_Error Number of terms in that taxonomy or WP_Error if the taxonomy does not exist. + * @return string|WP_Error Numeric string containing the number of terms in that + * taxonomy or WP_Error if the taxonomy does not exist. */ function wp_count_terms( $args = array(), $deprecated = '' ) { $use_legacy_args = false; diff --git a/tests/phpunit/tests/term/wpInsertTerm.php b/tests/phpunit/tests/term/wpInsertTerm.php index a28d3c4065..8fd3504650 100644 --- a/tests/phpunit/tests/term/wpInsertTerm.php +++ b/tests/phpunit/tests/term/wpInsertTerm.php @@ -43,7 +43,7 @@ class Tests_Term_WpInsertTerm extends WP_UnitTestCase { remove_filter( 'delete_term', array( $this, 'deleted_term_cb' ), 10, 5 ); $this->assertNull( term_exists( $term ) ); $this->assertNull( term_exists( $t['term_id'] ) ); - $this->assertEquals( $initial_count, wp_count_terms( array( 'taxonomy' => $taxonomy ) ) ); + $this->assertSame( $initial_count, wp_count_terms( array( 'taxonomy' => $taxonomy ) ) ); } public function test_wp_insert_term_taxonomy_does_not_exist() {