get_boundary_post

Retrieves the boundary post.

Description

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

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

Returns (null|array)

Array containing the boundary post object if successful, null otherwise.

Parameters (4)

0. $in_same_term — Optional. (constant) => false
Whether returned post should be in a same taxonomy term. Default false.
1. $excluded_terms — Optional. (string) => ''
Array or comma-separated list of excluded term IDs. Default empty.
2. $start — Optional. (constant) => true
Whether to retrieve first or last post. Default true
3. $taxonomy — Optional. (string) => 'category'
Taxonomy, if $in_same_term is true. Default category..

Usage

  1. if ( !function_exists( 'get_boundary_post' ) ) { 
  2. require_once ABSPATH . WPINC . '/link-template.php'; 
  3.  
  4. // Optional. Whether returned post should be in a same taxonomy term. 
  5. // Default false. 
  6. $in_same_term = false; 
  7.  
  8. // Optional. Array or comma-separated list of excluded term IDs. 
  9. // Default empty. 
  10. $excluded_terms = ''; 
  11.  
  12. // Optional. Whether to retrieve first or last post. Default true 
  13. $start = true; 
  14.  
  15. // Optional. Taxonomy, if $in_same_term is true. Default 'category'. 
  16. $taxonomy = 'category'; 
  17.  
  18. // NOTICE! Understand what this does before running. 
  19. $result = get_boundary_post($in_same_term, $excluded_terms, $start, $taxonomy); 
  20.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/link-template.php  
  1. function get_boundary_post( $in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category' ) { 
  2. $post = get_post(); 
  3. if ( ! $post || ! is_single() || is_attachment() || ! taxonomy_exists( $taxonomy ) ) 
  4. return null; 
  5.  
  6. $query_args = array( 
  7. 'posts_per_page' => 1,  
  8. 'order' => $start ? 'ASC' : 'DESC',  
  9. 'update_post_term_cache' => false,  
  10. 'update_post_meta_cache' => false 
  11. ); 
  12.  
  13. $term_array = array(); 
  14.  
  15. if ( ! is_array( $excluded_terms ) ) { 
  16. if ( ! empty( $excluded_terms ) ) 
  17. $excluded_terms = explode( ', ', $excluded_terms ); 
  18. else 
  19. $excluded_terms = array(); 
  20.  
  21. if ( $in_same_term || ! empty( $excluded_terms ) ) { 
  22. if ( $in_same_term ) 
  23. $term_array = wp_get_object_terms( $post->ID, $taxonomy, array( 'fields' => 'ids' ) ); 
  24.  
  25. if ( ! empty( $excluded_terms ) ) { 
  26. $excluded_terms = array_map( 'intval', $excluded_terms ); 
  27. $excluded_terms = array_diff( $excluded_terms, $term_array ); 
  28.  
  29. $inverse_terms = array(); 
  30. foreach ( $excluded_terms as $excluded_term ) 
  31. $inverse_terms[] = $excluded_term * -1; 
  32. $excluded_terms = $inverse_terms; 
  33.  
  34. $query_args[ 'tax_query' ] = array( array( 
  35. 'taxonomy' => $taxonomy,  
  36. 'terms' => array_merge( $term_array, $excluded_terms ) 
  37. ) ); 
  38.  
  39. return get_posts( $query_args );