Changeset 49947

Timestamp:

01/08/2021 03:22:17 PM (4 years ago)

Author:

johnbillion

Message:

Taxonomy: Correct and clarify documentation for the return types of term query functions.

See #51800, #38266

Location:

trunk

Files:

• src/wp-includes/class-wp-term-query.php (modified) (3 diffs)
• src/wp-includes/taxonomy.php (modified) (3 diffs)
• tests/phpunit/tests/term/wpInsertTerm.php (modified) (1 diff)

trunk/src/wp-includes/class-wp-term-query.php

@@ -286 +286 @@
 
     /**
-     * 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 ) {
@@ -299 +303 @@
 
     /**
-     * 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
@@ -305 +338 @@
      * @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() {

trunk/src/wp-includes/taxonomy.php

@@ -1132 +1132 @@
 
 /**
- * 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
@@ -1178 +1182 @@
  *                                 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 = '' ) {
@@ -1746 +1751 @@
  *                                 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 = '' ) {

trunk/tests/phpunit/tests/term/wpInsertTerm.php

@@ -44 +44 @@
         $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 ) ) );
     }