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

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

The following functions are documented here.

For more information about all functions, classes or hooks search the Code Reference for this plugin.

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

Basic Usage

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.
(array)(optional) Overwrite the defaults.

Default $args are:

$defaults = array(
	'taxonomies'     => ''           // string or array with multiple taxonomies.
	'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'
	'include_terms'  => '',          // string or array with term IDs
	'exclude_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'
	'post_thumbnail' => false,       // (bool) return only posts with a post thumbnail.
	'meta_key'       => '',          // (string) Meta key
	'meta_value'     => '',          // (mixed) Post meta value 
	'meta_compare'   => '',          // (string) Operator used for comparing the meta_value. 
	'meta_type'      => '',          // (string) Data type that the meta_value will be CAST to for comparisons.
	'public_only'    => false,       // (bool) Exclude private posts from current user
    'include_self'   => false,       // (bool) Include current post 

If the taxonomies argument is left empty the posts are queried in all taxonomies.

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_get_related_posts' ) ) {

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

	$related_posts = km_rpbt_get_related_posts( $post->ID, $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_get_related_posts() function above).

Default $args are:

$defaults = array(
	'itemtag'       => 'dl', // 'figure' or 'dl' depending if your theme supports HTML5
	'icontag'       => 'dt', // 'div' or 'dt' depending if your theme supports HTML5
	'captiontag'    => 'dd', // 'figcaption' or 'dd' depending if your theme supports HTML5
	'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
    'gallery_class' => 'gallery',
	'type'          => '', // widget or shortcode
	'show_date'     => false, // true or false


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_get_related_posts() function.

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

	$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_get_related_posts( $post_id, $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 );