/**
* Get result.
*
* Works for all query types.
*
* @return array
*/
public function get_result()
{
if (!method_exists($this->query, 'query')) {
return [];
}
$this->parse_args($this->args);
return $this->query->query($this->get_query_args());
}
/**
* Retrieve 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 {@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
* the array of terms, along with the $taxonomies and $args.
*
* The {@see 'list_terms_exclusions'} filter passes the compiled exclusions along with
* the $args.
*
* The {@see 'get_terms_orderby'} filter passes the `ORDER BY` clause for the query
* along with the $args array.
*
* Prior to 4.5.0, the first parameter of `get_terms()` was a taxonomy or list of taxonomies:
*
* $terms = get_terms( 'post_tag', array(
* 'hide_empty' => false,
* ) );
*
* Since 4.5.0, taxonomies should be passed via the 'taxonomy' argument in the `$args` array:
*
* $terms = get_terms( array(
* 'taxonomy' => 'post_tag',
* 'hide_empty' => false,
* ) );
*
* @since 2.3.0
* @since 4.2.0 Introduced 'name' and 'childless' parameters.
* @since 4.4.0 Introduced the ability to pass 'term_id' as an alias of 'id' for the `orderby` parameter.
* Introduced the 'meta_query' and 'update_term_meta_cache' parameters. Converted to return
* a list of WP_Term objects.
* @since 4.5.0 Changed the function signature so that the `$args` array can be provided as the first parameter.
* Introduced 'meta_key' and 'meta_value' parameters. Introduced the ability to order results by metadata.
*
* @internal The `$deprecated` parameter is parsed for backward compatibility only.
*
* @global wpdb $wpdb WordPress database abstraction object.
* @global array $wp_filter
*
* @param array|string $args {
* Optional. Array or string of arguments to get terms.
*
* @type string|array $taxonomy Taxonomy name, or array of taxonomies, to which results should
* be limited.
* @type string $orderby Field(s) to order terms by. Accepts term fields ('name', 'slug',
* 'term_group', 'term_id', 'id', 'description'), 'count' for term
* taxonomy count, 'include' to match the 'order' of the $include param,
* 'meta_value', 'meta_value_num', the value of `$meta_key`, the array
* keys of `$meta_query`, or '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.
* Default empty array.
* @type array|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
* 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
* positive number. Default ''|0 (all).
* @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), 'ids' (returns an array of ids), 'id=>parent' (returns
* an associative array with ids as keys, parent term IDs as values),
* 'names' (returns an array of term names), 'count' (returns the number
* of matching terms), 'id=>name' (returns an associative array with ids
* as keys, term names as values), or 'id=>slug' (returns an associative
* array with ids as keys, term slugs as values). Default 'all'.
* @type string|array $name Optional. Name or array of names to return term(s) for. Default empty.
* @type string|array $slug Optional. Slug or array of slugs to return term(s) for. Default empty.
* @type bool $hierarchical Whether to include terms that have non-empty descendants (even
* if $hide_empty is set to true). Default true.
* @type string $search Search criteria to match terms. Will be SQL-formatted with
* wildcards before and after. Default empty.
* @type string $name__like Retrieve terms with criteria by which a term is LIKE $name__like.
* Default empty.
* @type string $description__like Retrieve terms where the description is LIKE $description__like.
* Default empty.
* @type bool $pad_counts Whether to pad the quantity of a term's children in the quantity
* of each term's "count" object variable. Default false.
* @type string $get Whether to return terms regardless of ancestry or whether the terms
* are empty. Accepts 'all' or empty (disabled). Default empty.
* @type int $child_of Term ID to retrieve child terms of. If multiple taxonomies
* are passed, $child_of is ignored. Default 0.
* @type int|string $parent Parent term ID to retrieve direct-child terms of. Default empty.
* @type bool $childless True to limit results to terms that have no children. This parameter
* has no effect on non-hierarchical taxonomies. Default false.
* @type string $cache_domain Unique cache key to be produced when this query is stored in an
* object cache. Default is 'core'.
* @type bool $update_term_meta_cache Whether to prime meta caches for matched terms. Default true.
* @type array $meta_query Meta query clauses to limit retrieved terms by.
* See `WP_Meta_Query`. Default empty.
* @type string $meta_key Limit terms to those matching a specific metadata key. Can be used in
* conjunction with `$meta_value`.
* @type string $meta_value Limit terms to those matching a specific metadata value. Usually used
* in conjunction with `$meta_key`.
* }
* @param array $deprecated Argument array, when using the legacy function parameter format. If present, this
* parameter will be interpreted as `$args`, and the first function parameter will
* be parsed as a taxonomy or array of taxonomies.
* @return array|int|WP_Error List of WP_Term instances and their children. Will return WP_Error, if any of $taxonomies
* do not exist.
*/
function get_terms($args = array(), $deprecated = '')
{
global $wpdb;
$term_query = new WP_Term_Query();
/*
* Legacy argument format ($taxonomy, $args) takes precedence.
*
* We detect legacy argument format by checking if
* (a) a second non-empty parameter is passed, or
* (b) the first parameter shares no keys with the default array (ie, it's a list of taxonomies)
*/
$_args = wp_parse_args($args);
$key_intersect = array_intersect_key($term_query->query_var_defaults, (array) $_args);
$do_legacy_args = $deprecated || empty($key_intersect);
if ($do_legacy_args) {
$taxonomies = (array) $args;
$args = wp_parse_args($deprecated);
$args['taxonomy'] = $taxonomies;
} else {
$args = wp_parse_args($args);
if (isset($args['taxonomy']) && null !== $args['taxonomy']) {
$args['taxonomy'] = (array) $args['taxonomy'];
}
}
if (!empty($args['taxonomy'])) {
foreach ($args['taxonomy'] as $taxonomy) {
if (!taxonomy_exists($taxonomy)) {
return new WP_Error('invalid_taxonomy', __('Invalid taxonomy.'));
}
}
}
$terms = $term_query->query($args);
// Count queries are not filtered, for legacy reasons.
if (!is_array($terms)) {
return $terms;
}
/**
* Filters the found terms.
*
* @since 2.3.0
* @since 4.6.0 Added the `$term_query` parameter.
*
* @param array $terms Array of found terms.
* @param array $taxonomies An array of taxonomies.
* @param array $args An array of get_terms() arguments.
* @param WP_Term_Query $term_query The WP_Term_Query object.
*/
return apply_filters('get_terms', $terms, $term_query->query_vars['taxonomy'], $term_query->query_vars, $term_query);
}
/**
* @ticket 38295
* @group cache
*/
public function test_count_query_cache_should_be_invalidated_with_incrementor_bump()
{
register_taxonomy('wptests_tax_1', 'post');
$terms = self::factory()->term->create_many(2, array('taxonomy' => 'wptests_tax_1'));
$query = new WP_Term_Query(array('taxonomy' => 'wptests_tax_1', 'fields' => 'count', 'hide_empty' => false));
$count = $query->get_terms();
$this->assertEquals(2, $count);
wp_delete_term($terms[0], 'wptests_tax_1');
$query = new WP_Term_Query(array('taxonomy' => 'wptests_tax_1', 'fields' => 'count', 'hide_empty' => false));
$count = $query->get_terms();
$this->assertEquals(1, $count);
}
/**
* @ticket 37198
* @group cache
*/
public function test_object_ids_cache_should_be_invalidated_by_term_relationship_change()
{
register_taxonomy('wptests_tax_1', 'post');
$p = self::factory()->post->create();
$terms = self::factory()->term->create_many(2, array('taxonomy' => 'wptests_tax_1'));
wp_set_object_terms($p, array($terms[0]), 'wptests_tax_1');
$query = new WP_Term_Query(array('taxonomy' => 'wptests_tax_1', 'object_ids' => $p, 'fields' => 'ids'));
$found = $query->get_terms();
$this->assertEqualSets(array($terms[0]), $found);
wp_set_object_terms($p, array($terms[1]), 'wptests_tax_1');
$query = new WP_Term_Query(array('taxonomy' => 'wptests_tax_1', 'object_ids' => $p, 'fields' => 'ids'));
$found = $query->get_terms();
$this->assertEqualSets(array($terms[1]), $found);
}
/**
* @ticket 23261
* @ticket 37904
*/
public function test_orderby_include_with_comma_separated_list()
{
register_taxonomy('wptests_tax_1', 'post');
$t1 = self::factory()->term->create_and_get(array('taxonomy' => 'wptests_tax_1'));
$t2 = self::factory()->term->create_and_get(array('taxonomy' => 'wptests_tax_1'));
$query = new WP_Term_Query(array('include' => "{$t1->term_id},{$t2->term_id}", 'orderby' => 'include', 'hide_empty' => false));
$terms = $query->get_terms();
$this->assertEquals(array($t1, $t2), $terms);
}
