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