get_boundary_post( bool $in_same_term = false, array|string $excluded_terms = '', bool $start = true, string $taxonomy = 'category' )

Retrieves the boundary post.


Description Description

Boundary being either the first or last post by publish date within the constraints specified by $in_same_term or $excluded_terms.


Top ↑

Parameters Parameters

$in_same_term

(bool) (Optional) Whether returned post should be in a same taxonomy term.

Default value: false

$excluded_terms

(array|string) (Optional) Array or comma-separated list of excluded term IDs.

Default value: ''

$start

(bool) (Optional) Whether to retrieve first or last post. Default true

Default value: true

$taxonomy

(string) (Optional) Taxonomy, if $in_same_term is true.

Default value: 'category'


Top ↑

Return Return

(null|array) Array containing the boundary post object if successful, null otherwise.


Top ↑

More Information More Information

get_boundary_post() will set the post pointer to the first post.


Top ↑

Source Source

File: wp-includes/link-template.php

function get_boundary_post( $in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category' ) {
	$post = get_post();
	if ( ! $post || ! is_single() || is_attachment() || ! taxonomy_exists( $taxonomy ) ) {
		return null;
	}

	$query_args = array(
		'posts_per_page'         => 1,
		'order'                  => $start ? 'ASC' : 'DESC',
		'update_post_term_cache' => false,
		'update_post_meta_cache' => false,
	);

	$term_array = array();

	if ( ! is_array( $excluded_terms ) ) {
		if ( ! empty( $excluded_terms ) ) {
			$excluded_terms = explode( ',', $excluded_terms );
		} else {
			$excluded_terms = array();
		}
	}

	if ( $in_same_term || ! empty( $excluded_terms ) ) {
		if ( $in_same_term ) {
			$term_array = wp_get_object_terms( $post->ID, $taxonomy, array( 'fields' => 'ids' ) );
		}

		if ( ! empty( $excluded_terms ) ) {
			$excluded_terms = array_map( 'intval', $excluded_terms );
			$excluded_terms = array_diff( $excluded_terms, $term_array );

			$inverse_terms = array();
			foreach ( $excluded_terms as $excluded_term ) {
				$inverse_terms[] = $excluded_term * -1;
			}
			$excluded_terms = $inverse_terms;
		}

		$query_args['tax_query'] = array(
			array(
				'taxonomy' => $taxonomy,
				'terms'    => array_merge( $term_array, $excluded_terms ),
			),
		);
	}

	return get_posts( $query_args );
}


Top ↑

Changelog Changelog

Changelog
Version Description
2.8.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by stevenlinx

    Migrate from Codex:

    Link with title of first post in current post’s category:

    <?php
       $first= get_boundary_post(true, , true, 'category');
       if (!empty($first)) { foreach ($first as $post) { ?>
       <a href="<?php echo the_permalink($post->ID); ?>"><?php echo $post->post_title; ?></a>
    <?php }} ?>
    

    Link with title of latest post in current post’s category:

    <?php
       $latest= get_boundary_post(true, , false, 'category');
       if (!empty($latest)) { foreach ($latest as $post) { ?>
       <a href="<?php echo the_permalink($post->ID); ?>"><?php echo $post->post_title; ?></a>
    <?php }} ?>
    

You must log in before being able to contribute a note or feedback.