get_objects_in_term() │ WP 2.3.0

Gets the IDs of objects (usually posts) that relate to the specified element of the specified taxonomy.

The $taxonomies parameter is required. If the specified taxonomy is not found, the function will return a WP_Error object, which can be handled to get an error message... All this is somewhat similar to Exceptions in PHP.

The $term_ids parameter is checked differently than $taxonomies - there is no check for the existence of the term, and if it is not in the database, it is simply skipped (not considered).

The function does not cache the query. The query is made directly to the database and is point-specific - i.e., it only retrieves the IDs of objects.

The function retrieves the IDs of posts only from the specified taxonomy elements - nesting is not taken into account. That is, if category 5 has subcategories 6 and 7, and we specified only 5, then only the IDs of posts from 5 will be retrieved.

1 time — 0.000449 sec (fast) | 50000 times — 13.14 sec (slow) | PHP 7.1.2, WP 4.7.5

No Hooks.

Returns

String[]|WP_Error.

WP_Error, if any of the specified taxonomies do not exist.
An empty array when no objects are found for the specified taxonomy and terms.
An array with the IDs of found terms.

Usage

get_objects_in_term( $term_ids, $taxonomies, $args = array() );

$term_ids(int/array) (required): ID of the taxonomy element (term) or an array of several IDs.
$taxonomies(string/array) (required): Name of the taxonomy or an array of names of several taxonomies.
If any of the specified taxonomies do not exist, the function will return WP_Error...
$args(array/string): Query parameters. Currently, only one parameter can be specified - order. It is responsible for the sorting direction and can be: ASC or DESC. Sorting occurs by the column object_ids, i.e., by the IDs of the terms.
Default: array()

Examples

#1 Get the ID of all posts from the category

Here we get the IDs of the posts from category 33:

$post_ids = get_objects_in_term( 33, 'category' );

print_r( $post_ids );
/*
Array (
	[0] => 72
	[1] => 372
	[2] => 800
)
*/

#2 Get the IDs of all posts from several taxonomies and their elements

Here 33 is the 'category' tax element, and 12 is the 'post_tag' tax element:

$objects = get_objects_in_term( [ 33, 12 ], [ 'category', 'post_tag' ] );

print_r( $objects );
/*
Array (
	[0] => 72
	[1] => 372
	[2] => 800
	[3] => 2818
	[4] => 2971
	[5] => 3755
)
*/

#3 Checking the return value

$objects = get_objects_in_term( [ 33, 12 ], [ 'category', 'post_tag' ] );

if( is_wp_error( $objects ) ){
	echo 'The taxonomy is incorrect';
}
elseif( ! $objects ){
	echo 'No objects';
}
else {
	echo 'there are objects!';
	print_r( $objects );
}

#4 List of all post tags from the specified category

This example shows how to get a list of all post tags that are in a specified category (in this case, the current category) with the least amount of code.

if( is_category() ){

	$term_id = get_queried_object_id(); // the id of the current category

	// collect the IDs of all nested categories
	$term_ids = get_term_children( $term_id, 'category' );
	array_push( $term_ids, $term_id );

	$post_ids = get_objects_in_term( $term_ids, 'category' );

	if ( $post_ids && ! is_wp_error($post_ids) ) {

		$tags = wp_get_object_terms( $post_ids, 'post_tag' );

		if ( $tags && ! is_wp_error( $tags ) ){ 

			$list = [];
			foreach( $tags as $tag ){
				$list[] = '<a href="'. get_term_link( $tag, 'post_tag') .'">'. esc_html( $tag->name ) .'</a>';
			}

			echo '
			<ul>
				<li>'. implode( "</li>\n<li>", $list ) .'</li>
			</ul>
			';
		}
	}

}

Notes

Global. wpdb. $wpdb WordPress database abstraction object.

Changelog

Since 2.3.0

Introduced.

`get_objects_in_term() get objects in term` code ^{WP 6.8.3}

wp-includes/taxonomy.php

function get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
	global $wpdb;

	if ( ! is_array( $term_ids ) ) {
		$term_ids = array( $term_ids );
	}
	if ( ! is_array( $taxonomies ) ) {
		$taxonomies = array( $taxonomies );
	}
	foreach ( (array) $taxonomies as $taxonomy ) {
		if ( ! taxonomy_exists( $taxonomy ) ) {
			return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
		}
	}

	$defaults = array( 'order' => 'ASC' );
	$args     = wp_parse_args( $args, $defaults );

	$order = ( 'desc' === strtolower( $args['order'] ) ) ? 'DESC' : 'ASC';

	$term_ids = array_map( 'intval', $term_ids );

	$taxonomies = "'" . implode( "', '", array_map( 'esc_sql', $taxonomies ) ) . "'";
	$term_ids   = "'" . implode( "', '", $term_ids ) . "'";

	$sql = "SELECT tr.object_id FROM $wpdb->term_relationships AS tr INNER JOIN $wpdb->term_taxonomy AS tt ON tr.term_taxonomy_id = tt.term_taxonomy_id WHERE tt.taxonomy IN ($taxonomies) AND tt.term_id IN ($term_ids) ORDER BY tr.object_id $order";

	$last_changed = wp_cache_get_last_changed( 'terms' );
	$cache_key    = 'get_objects_in_term:' . md5( $sql ) . ":$last_changed";
	$cache        = wp_cache_get( $cache_key, 'term-queries' );
	if ( false === $cache ) {
		$object_ids = $wpdb->get_col( $sql );
		wp_cache_set( $cache_key, $object_ids, 'term-queries' );
	} else {
		$object_ids = (array) $cache;
	}

	if ( ! $object_ids ) {
		return array();
	}
	return $object_ids;
}