diff -r 34716fd837a4 -r be944660c56a wp/wp-includes/class-wp-term-query.php --- a/wp/wp-includes/class-wp-term-query.php Tue Dec 15 15:52:01 2020 +0100 +++ b/wp/wp-includes/class-wp-term-query.php Wed Sep 21 18:19:35 2022 +0200 @@ -94,31 +94,31 @@ * * @type string|array $taxonomy Taxonomy name, or array of taxonomies, to which results should * be limited. - * @type int|array $object_ids Optional. Object ID, or array of object IDs. Results will be + * @type int|int[] $object_ids Optional. Object ID, or array of object IDs. Results will be * limited to terms associated with these objects. * @type string $orderby Field(s) to order terms by. Accepts: - * - term fields ('name', 'slug', 'term_group', 'term_id', 'id', + * * term fields ('name', 'slug', 'term_group', 'term_id', 'id', * 'description', 'parent', 'term_order'). Unless `$object_ids` * is not empty, 'term_order' is treated the same as 'term_id'. - * - 'count' for term taxonomy count. - * - 'include' to match the 'order' of the $include param. - * - 'slug__in' to match the 'order' of the $slug param. - * - 'meta_value', 'meta_value_num'. - * - the value of `$meta_key`. - * - the array keys of `$meta_query`. - * - 'none' to omit the ORDER BY clause. + * * 'count' to use the number of objects associated with the term. + * * 'include' to match the 'order' of the $include param. + * * 'slug__in' to match the 'order' of the $slug param. + * * 'meta_value', 'meta_value_num'. + * the value of `$meta_key`. + * the array keys of `$meta_query`. + * * 'none' to omit the ORDER BY clause. * Defaults to 'name'. * @type string $order Whether to order terms in ascending or descending order. * Accepts 'ASC' (ascending) or 'DESC' (descending). * Default 'ASC'. * @type bool|int $hide_empty Whether to hide terms not assigned to any posts. Accepts * 1|true or 0|false. Default 1|true. - * @type array|string $include Array or comma/space-separated string of term IDs to include. + * @type int[]|string $include Array or comma/space-separated string of term IDs to include. * Default empty array. - * @type array|string $exclude Array or comma/space-separated string of term IDs to exclude. + * @type int[]|string $exclude Array or comma/space-separated string of term IDs to exclude. * If $include is non-empty, $exclude is ignored. * Default empty array. - * @type array|string $exclude_tree Array or comma/space-separated string of term IDs to exclude + * @type int[]|string $exclude_tree Array or comma/space-separated string of term IDs to exclude * along with all of their descendant terms. If $include is * non-empty, $exclude_tree is ignored. Default empty array. * @type int|string $number Maximum number of terms to return. Accepts ''|0 (all) or any @@ -127,20 +127,20 @@ * See #41796 for details. * @type int $offset The number by which to offset the terms query. Default empty. * @type string $fields Term fields to query for. Accepts: - * - 'all' Returns an array of complete term objects (`WP_Term[]`). - * - 'all_with_object_id' Returns an array of term objects + * * 'all' Returns an array of complete term objects (`WP_Term[]`). + * * 'all_with_object_id' Returns an array of term objects * with the 'object_id' param (`WP_Term[]`). Works only * when the `$object_ids` parameter is populated. - * - 'ids' Returns an array of term IDs (`int[]`). - * - 'tt_ids' Returns an array of term taxonomy IDs (`int[]`). - * - 'names' Returns an array of term names (`string[]`). - * - 'slugs' Returns an array of term slugs (`string[]`). - * - 'count' Returns the number of matching terms (`int`). - * - 'id=>parent' Returns an associative array of parent term IDs, + * * 'ids' Returns an array of term IDs (`int[]`). + * * 'tt_ids' Returns an array of term taxonomy IDs (`int[]`). + * * 'names' Returns an array of term names (`string[]`). + * * 'slugs' Returns an array of term slugs (`string[]`). + * * 'count' Returns the number of matching terms (`int`). + * * 'id=>parent' Returns an associative array of parent term IDs, * keyed by term ID (`int[]`). - * - 'id=>name' Returns an associative array of term names, + * * 'id=>name' Returns an associative array of term names, * keyed by term ID (`string[]`). - * - 'id=>slug' Returns an associative array of term slugs, + * * 'id=>slug' Returns an associative array of term slugs, * keyed by term ID (`string[]`). * Default 'all'. * @type bool $count Whether to return a term count. If true, will take precedence @@ -149,7 +149,7 @@ * Default empty. * @type string|array $slug Optional. Slug or array of slugs to return term(s) for. * Default empty. - * @type int|array $term_taxonomy_id Optional. Term taxonomy ID, or array of term taxonomy IDs, + * @type int|int[] $term_taxonomy_id Optional. Term taxonomy ID, or array of term taxonomy IDs, * to match when querying terms. * @type bool $hierarchical Whether to include terms that have non-empty descendants * (even if $hide_empty is set to true). Default true. @@ -258,7 +258,7 @@ $query['offset'] = absint( $query['offset'] ); // 'parent' overrides 'child_of'. - if ( 0 < intval( $query['parent'] ) ) { + if ( 0 < (int) $query['parent'] ) { $query['child_of'] = false; } @@ -285,12 +285,16 @@ } /** - * 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,41 @@ } /** - * 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' * * @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; @@ -321,9 +353,9 @@ * * @since 4.6.0 * - * @param WP_Term_Query $this Current instance of WP_Term_Query. + * @param WP_Term_Query $this Current instance of WP_Term_Query (passed by reference). */ - do_action( 'pre_get_terms', $this ); + do_action_ref_array( 'pre_get_terms', array( &$this ) ); $taxonomies = (array) $args['taxonomy']; @@ -346,7 +378,7 @@ } // 'parent' overrides 'child_of'. - if ( 0 < intval( $args['parent'] ) ) { + if ( 0 < (int) $args['parent'] ) { $args['child_of'] = false; } @@ -443,7 +475,7 @@ (array) get_terms( array( 'taxonomy' => reset( $taxonomies ), - 'child_of' => intval( $extrunk ), + 'child_of' => (int) $extrunk, 'fields' => 'ids', 'hide_empty' => 0, ) @@ -688,15 +720,15 @@ $this->terms = null; /** - * Filter the terms array before the query takes place. + * Filters the terms array before the query takes place. * - * Return a non-null value to bypass WordPress's default term queries. + * Return a non-null value to bypass WordPress' default term queries. * * @since 5.3.0 * * @param array|null $terms Return an array of term data to short-circuit WP's term query, * or null to allow WP queries to run normally. - * @param WP_Term_Query $this The WP_Term_Query instance, passed by reference. + * @param WP_Term_Query $query The WP_Term_Query instance, passed by reference. */ $this->terms = apply_filters_ref_array( 'terms_pre_query', array( $this->terms, &$this ) );