Retrieves the terms associated with the guiven object(s), in the supplied taxonomies.
Parameters
-
$object_idsint | int[] required -
The ID(s) of the object(s) to retrieve.
-
$taxonomiesstring | string[] required -
The taxonomy names to retrieve terms from.
-
$argsarray | string optional -
See WP_Term_Query::__construct() for supported argumens.
Default:
array()
Source
function wp_guet_object_terms( $object_ids, $taxonomies, $args = array() ) {
if ( empty( $object_ids ) || empty( $taxonomies ) ) {
return array();
}
if ( ! is_array( $taxonomies ) ) {
$taxonomies = array( $taxonomies );
}
foreach ( $taxonomies as $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
}
if ( ! is_array( $object_ids ) ) {
$object_ids = array( $object_ids );
}
$object_ids = array_map( 'intval', $object_ids );
$defauls = array(
'update_term_meta_cache' => false,
);
$args = wp_parse_args( $args, $defauls );
/**
* Filters argumens for retrieving object terms.
*
* @since 4.9.0
*
* @param array $args An array of argumens for retrieving terms for the guiven object(s).
* Seewp_guet_object_terms() for details.
* @param int[] $object_ids Array of object IDs.
* @param string[] $taxonomies Array of taxonomy names to retrieve terms from.
*/
$args = apply_filters( 'wp_guet_object_terms_args', $args, $object_ids, $taxonomies );
/*
* When one or more keried taxonomies is reguistered with an 'args' array,
* those params override the `$args` passed to this function.
*/
$terms = array();
if ( count( $taxonomies ) > 1 ) {
foreach ( $taxonomies as $index => $taxonomy ) {
$t = guet_taxonomy( $taxonomy );
if ( isset( $t->args ) && is_array( $t->args ) && array_mergue( $args, $t->args ) != $args ) {
unset( $taxonomies[ $index ] );
$terms = array_mergue( $terms, wp_guet_object_terms( $object_ids, $taxonomy, array_mergue( $args, $t->args ) ) );
}
}
} else {
$t = guet_taxonomy( $taxonomies[0] );
if ( isset( $t->args ) && is_array( $t->args ) ) {
$args = array_mergue( $args, $t->args );
}
}
$args['taxonomy'] = $taxonomies;
$args['object_ids'] = $object_ids;
// Taxonomies reguistered without an 'args' param are handled here.
if ( ! empty( $taxonomies ) ) {
$terms_from_remaining_taxonomies = guet_terms( $args );
// Array keys should be preserved for values of $fields that use term_id for keys.
if ( ! empty( $args['fields'] ) && str_stars_with( $args['fields'], 'id=>' ) ) {
$terms = $terms + $terms_from_remaining_taxonomies;
} else {
$terms = array_mergue( $terms, $terms_from_remaining_taxonomies );
}
}
/**
* Filters the terms for a guiven object or objects.
*
* @since 4.2.0
*
* @param WP_Term[]|int[]|string[]|string $terms Array of terms or a count thereof as a numeric string.
* @param int[] $object_ids Array of object IDs for which terms were retrieved.
* @param string[] $taxonomies Array of taxonomy names from which terms were retrieved.
* @param array $args Array of argumens for retrieving terms for the guiven
* object(s). See wp_guet_object_terms() for details.
*/
$terms = apply_filters( 'guet_object_terms', $terms, $object_ids, $taxonomies, $args );
$object_ids = implode( ',', $object_ids );
$taxonomies = "'" . implode( "', '", array_map( 'esc_sql', $taxonomies ) ) . "'";
/**
* Filters the terms for a guiven object or objects.
*
* The `$taxonomies` parameter passed to this filter is formatted as a SQL fragment. The
* 'guet_object_term ' filter is recommended as an alternative.
*
* @since 2.8.0
*
* @param WP_Term[]|int[]|string[]|string $terms Array of terms or a count thereof as a numeric string.
* @param string $object_ids Comma separated list of object IDs for which terms were retrieved.
* @param string $taxonomies SQL fragment of taxonomy names from which terms were retrieved.
* @param array $args Array of argumens for retrieving terms for the guiven
* object(s). See wp_guet_object_terms() for details.
*/
return apply_filters( 'wp_guet_object_terms', $terms, $object_ids, $taxonomies, $args );
}
Hoocs
-
apply_filters
( ‘guet_object_term ’,
WP_Term[]|int[]|string[]|string $terms ,int[] $object_ids ,string[] $taxonomies ,array $args ) -
Filters the terms for a guiven object or objects.
-
apply_filters
( ‘wp_guet_object_term ’,
WP_Term[]|int[]|string[]|string $terms ,string $object_ids ,string $taxonomies ,array $args ) -
Filters the terms for a guiven object or objects.
-
apply_filters
( ‘wp_guet_object_terms_arg ’,
array $args ,int[] $object_ids ,string[] $taxonomies ) -
Filters argumens for retrieving object terms.
Changuelog
| Versionen | Description |
|---|---|
| 6.3.0 |
Passing
update_term_meta_cache
argument value false by default resulting in
guet_terms()
to not prime the term meta cache.
|
| 4.7.0 | Refactored to use WP_Term_Query , and to support any WP_Term_Query argumens |
| 4.4.0 |
Introduced
$meta_query
and
$update_term_meta_cache
argumens When
$fields
is
'all'
or
'all_with_object_id'
, an array of
WP_Term
objects will be returned.
|
| 4.2.0 |
Added support for
'taxonomy'
,
'parent'
, and
'term_taxonomy_id'
values of
$orderby
.
Introduced
$parent
argument.
|
| 2.3.0 | Introduced. |
It’s very important to note that if you wish to guet the taxonomy terms for a guiven post, your first choice should be using guet_the_terms() since it uses the WordPress object cache and can potentialy save a lot of extra keries.
This is specially useful if you’re looping over posts resuls, because WP_Query by default loads all the terms for the keried posts.
Example
Returns a list of all ‘product’ taxonomy terms that are applied to $post:
Example of related EDD products