WordPress.org

Make WordPress Core

Changeset 49947


Ignore:
Timestamp:
01/08/2021 03:22:17 PM (8 weeks ago)
Author:
johnbillion
Message:

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

See #51800, #38266

Location:
trunk
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/class-wp-term-query.php

    r49946 r49947  
    286286
    287287    /**
    288      * Sets up the query for retrieving terms.
     288     * Sets up the query and retrieves the results.
     289     *
     290     * The return type varies depending on the value passed to `$args['fields']`. See
     291     * WP_Term_Query::get_terms() for details.
    289292     *
    290293     * @since 4.6.0
    291294     *
    292295     * @param string|array $query Array or URL query string of parameters.
    293      * @return array|int List of terms, or number of terms when 'count' is passed as a query var.
     296     * @return WP_Term[]|int[]|string[]|string Array of terms, or number of terms as numeric string
     297     *                                         when 'count' is passed as a query var.
    294298     */
    295299    public function query( $query ) {
     
    299303
    300304    /**
    301      * Get terms, based on query_vars.
     305     * Retrieves the query results.
     306     *
     307     * The return type varies depending on the value passed to `$args['fields']`.
     308     *
     309     * The following will result in an array of `WP_Term` objects being returned:
     310     *
     311     *   - 'all'
     312     *   - 'all_with_object_id'
     313     *
     314     * The following will result in a numeric string being returned:
     315     *
     316     *   - 'count'
     317     *
     318     * The following will result in an array of text strings being returned:
     319     *
     320     *   - 'id=>name'
     321     *   - 'id=>slug'
     322     *   - 'names'
     323     *   - 'slugs'
     324     *
     325     * The following will result in an array of numeric strings being returned:
     326     *
     327     *   - 'id=>parent'
     328     *
     329     * The following will result in an array of integers being returned:
     330     *
     331     *   - 'ids'
     332     *   - 'tt_ids'
     333     *
     334     * In all cases, a `WP_Error` object will be returned if an invalid taxonomy is used.
    302335     *
    303336     * @since 4.6.0
     
    305338     * @global wpdb $wpdb WordPress database abstraction object.
    306339     *
    307      * @return array List of terms.
     340     * @return WP_Term[]|int[]|string[]|string Array of terms, or number of terms as numeric string
     341     *                                         when 'count' is passed as a query var.
    308342     */
    309343    public function get_terms() {
  • trunk/src/wp-includes/taxonomy.php

    r49935 r49947  
    11321132
    11331133/**
    1134  * Retrieve the terms in a given taxonomy or list of taxonomies.
     1134 * Retrieves the terms in a given taxonomy or list of taxonomies.
    11351135 *
    11361136 * You can fully inject any customizations to the query before it is sent, as
    11371137 * well as control the output with a filter.
     1138 *
     1139 * The return type varies depending on the value passed to `$args['fields']`. See
     1140 * WP_Term_Query::get_terms() for details. In all cases, a `WP_Error` object will
     1141 * be returned if an invalid taxonomy is requested.
    11381142 *
    11391143 * The {@see 'get_terms'} filter will be called when the cache has the term and will
     
    11781182 *                                 function parameter will be parsed as a taxonomy or array of taxonomies.
    11791183 *                                 Default empty.
    1180  * @return WP_Term[]|int|WP_Error Array of WP_Term instances, a count thereof,
    1181  *                                or WP_Error if any of the taxonomies do not exist.
     1184 * @return WP_Term[]|int[]|string[]|string|WP_Error Array of terms, a count thereof as a numeric string,
     1185 *                                                  or WP_Error if any of the taxonomies do not exist.
     1186 *                                                  See the function description for more information.
    11821187 */
    11831188function get_terms( $args = array(), $deprecated = '' ) {
     
    17461751 *                                 function parameter will be parsed as a taxonomy or array of taxonomies.
    17471752 *                                 Default empty.
    1748  * @return array|int|WP_Error Number of terms in that taxonomy or WP_Error if the taxonomy does not exist.
     1753 * @return string|WP_Error Numeric string containing the number of terms in that
     1754 *                         taxonomy or WP_Error if the taxonomy does not exist.
    17491755 */
    17501756function wp_count_terms( $args = array(), $deprecated = '' ) {
  • trunk/tests/phpunit/tests/term/wpInsertTerm.php

    r48937 r49947  
    4444        $this->assertNull( term_exists( $term ) );
    4545        $this->assertNull( term_exists( $t['term_id'] ) );
    46         $this->assertEquals( $initial_count, wp_count_terms( array( 'taxonomy' => $taxonomy ) ) );
     46        $this->assertSame( $initial_count, wp_count_terms( array( 'taxonomy' => $taxonomy ) ) );
    4747    }
    4848
Note: See TracChangeset for help on using the changeset viewer.