This page is part of the plugin documentation for the Related Posts by Taxonomy plugin.

These functions can be used in your (child) theme’s templates to display related posts.

Use this function in your (child) theme template files to get the related posts by taxonomy.

Basic Usage

<?php km_rpbt_related_posts_by_taxonomy( $post_id, $taxonomies, $args  ); ?>

This function returns an array with related post objects or an empty array if no related posts were found.


(int)(required) The post ID to retrieve related posts for.
(string|array)(required) The taxonomies used by the related posts. For example: 'category' or array( 'category', 'customtaxonomy' ).
(array)(optional) Overwrite the defaults.

Default $args are:

$defaults = array(
	'post_types'     => 'post',      // string or array with multiple post type names
	'posts_per_page' => 5,           // return 5 posts
	'order'          => 'DESC',      // 'DESC', 'ASC' or 'RAND'
	'orderby'        => 'post_date', // 'post_date' or 'post_modified'
	'exclude_terms'  => '',          // string or array with term IDs
	'include_terms'  => '',          // string or array with term IDs
	'exclude_posts'  => '',          // string or array with post IDs
	'limit_posts'    => -1,          // don't limit posts
	'limit_year'     => '',          // number of years 
	'limit_month'    => '',          // number of months
	'fields'         => 'all',       // 'all' (return post objects), 'ids', 'names' or 'slugs'
	'related'        => true,        // (bool) search in related terms for the current post ID
	'post_thumbnail' => false,       // (bool) return only posts with a post thumbnail.
	'public_only'    => false,       // (bool) Exclude private posts
    'include_self'   => false,       // (bool) Include current post 

As you can see most arguments are the same as in The shortcode attributes.

Two additional arguments are the ‘fields’ and ‘post_thumbnail’ arguments

(string) Return full post objects, IDs, post titles or post slugs. Default is ‘all’.

  • ‘all’ – return array of post objects
  • ‘ids’ – return array of post IDs
  • ‘names’ – return array of post titles
  • ‘slugs’ – return array of post slugs
(bool) Return related posts that have a post thumbnail. Default is false.

  • true (1) – return array of posts that have a post thumbnail
  • false (0) – return array of posts regardless if posts have a post thumbnail (default)


Get the latest 10 post related by categories and tags, excluding term ID’s ’12’ and ’34’:

// check if the function exists
if ( function_exists( 'km_rpbt_related_posts_by_taxonomy' ) ) {

	$args = array(
		'posts_per_page' => 10,
		'exclude_terms'  => array( 12, 34 ),

	$taxonomies = array( 'category', 'post_tag' );

	$related_posts = km_rpbt_related_posts_by_taxonomy( $post->ID, $taxonomies, $args );

	if ( $related_posts ) {

		echo '<h2>Related Posts</h2>';
		echo '<ul>';

		// Loop through the related posts.
		foreach ( (array) $related_posts as $related ) {

			echo '<li><a href="' . get_permalink( $related->ID ) . '">' . $related->post_title . '</a></li>';

		echo '</ul>';

Basic Usage

<?php km_rpbt_related_posts_by_taxonomy_gallery( $args, $related_posts  ); ?>

This function (introduced with version 0.2) lets you display related post thumbnails the same way the widget and shortcode does. The display is similar as the gallery shortcode. Use this function in your (child) theme’s template files.

(string|array)(optional) The arguments for post thumbnail gallery display you want to override.
(array)(required) Array of related post objects (see km_rpbt_related_posts_by_taxonomy() function above).

Default $args are:

$defaults = array(
	'itemtag'      => 'dl',
	'icontag'      => 'dt',
	'captiontag'   => 'dd',
	'id'           => $post->ID,   // post id 
	'columns'      => 3,           // zero or positive number
	'size'         => thumbnail,   // 'thumbnail', 'medium', 'large', 'full' and custom sizes set by your theme
	'caption'      => 'post_title', // 'post_title' or a custom string
    'link_caption' => false, // Link caption to post


For example, display six medium related post thumbnails in two columns on a single post (in single.php) related by categories.

// first get the related post objects with the km_rpbt_related_posts_by_taxonomy() function.

// check if the function already exists
if ( function_exists( 'km_rpbt_related_posts_by_taxonomy' ) ) {

	$args = array( 
		'posts_per_page' => 6,
		'post_thumbnail' => true, // only gets the posts that have a post thumbnail

	$taxonomies = array( 'category' );
	$post_id =  $post->ID; // post id available inside the loop.

	$related_posts = km_rpbt_related_posts_by_taxonomy( $post_id , $taxonomies, $args );

	// check if related post were found
	if ( $related_posts ) {

		$args = array(
			'columns'    => 2,
			'size'       => 'medium', // Default "thumbnail", "medium", "large", "full"

		// display the related post thumbnail gallery
		echo km_rpbt_related_posts_by_taxonomy_gallery( $args, $related_posts );

Use this function in your (child) theme template files to cache related posts. This function uses the same arguments as the km_rpbt_related_posts_by_taxonomy() function. After using this function the posts for the same query are returned from cache for the shortcode and widget. See the cache documentation.

Basic Usage

<?php km_rpbt_cache_related_posts( $post_id = 0, $taxonomies = 'category', $args = '' ); ?>

See this example for how to use the function in your (child) theme’s template files