get_adjacent_post

Retrieves the adjacent post.

Description

(null|string|WP_Post) get_adjacent_post( (constant) $in_same_term = false, (string) $excluded_terms = '', (constant) $previous = true, (string) $taxonomy = 'category' ); 

Can either be next or previous post.

Returns (null|string|WP_Post)

Post object if successful. Null if global $post is not set. Empty string if no corresponding post exists.

Parameters (4)

0. $in_same_term — Optional. (constant) => false
Whether 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. $previous — Optional. (constant) => true
Whether to retrieve previous post. Default true
3. $taxonomy — Optional. (string) => 'category'
Taxonomy, if $in_same_term is true. Default category..

Usage

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

Defined (1)

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

/wp-includes/link-template.php  
  1. function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previous = true, $taxonomy = 'category' ) { 
  2. global $wpdb; 
  3.  
  4. if ( ( ! $post = get_post() ) || ! taxonomy_exists( $taxonomy ) ) 
  5. return null; 
  6.  
  7. $current_post_date = $post->post_date; 
  8.  
  9. $join = ''; 
  10. $where = ''; 
  11. $adjacent = $previous ? 'previous' : 'next'; 
  12.  
  13. if ( $in_same_term || ! empty( $excluded_terms ) ) { 
  14. if ( ! empty( $excluded_terms ) && ! is_array( $excluded_terms ) ) { 
  15. // back-compat, $excluded_terms used to be $excluded_terms with IDs separated by " and " 
  16. if ( false !== strpos( $excluded_terms, ' and ' ) ) { 
  17. _deprecated_argument( __FUNCTION__, '3.3.0', sprintf( __( 'Use commas instead of %s to separate excluded terms.' ), "'and'" ) ); 
  18. $excluded_terms = explode( ' and ', $excluded_terms ); 
  19. } else { 
  20. $excluded_terms = explode( ', ', $excluded_terms ); 
  21.  
  22. $excluded_terms = array_map( 'intval', $excluded_terms ); 
  23.  
  24. if ( $in_same_term ) { 
  25. $join .= " INNER JOIN $wpdb->term_relationships AS tr ON p.ID = tr.object_id INNER JOIN $wpdb->term_taxonomy tt ON tr.term_taxonomy_id = tt.term_taxonomy_id"; 
  26. $where .= $wpdb->prepare( "AND tt.taxonomy = %s", $taxonomy ); 
  27.  
  28. if ( ! is_object_in_taxonomy( $post->post_type, $taxonomy ) ) 
  29. return ''; 
  30. $term_array = wp_get_object_terms( $post->ID, $taxonomy, array( 'fields' => 'ids' ) ); 
  31.  
  32. // Remove any exclusions from the term array to include. 
  33. $term_array = array_diff( $term_array, (array) $excluded_terms ); 
  34. $term_array = array_map( 'intval', $term_array ); 
  35.  
  36. if ( ! $term_array || is_wp_error( $term_array ) ) 
  37. return ''; 
  38.  
  39. $where .= " AND tt.term_id IN (" . implode( ', ', $term_array ) . ")"; 
  40.  
  41. /** 
  42. * Filters the IDs of terms excluded from adjacent post queries. 
  43. * The dynamic portion of the hook name, `$adjacent`, refers to the type 
  44. * of adjacency, 'next' or 'previous'. 
  45. * @since 4.4.0 
  46. * @param string $excluded_terms Array of excluded term IDs. 
  47. */ 
  48. $excluded_terms = apply_filters( "get_{$adjacent}_post_excluded_terms", $excluded_terms ); 
  49.  
  50. if ( ! empty( $excluded_terms ) ) { 
  51. $where .= " AND p.ID NOT IN ( SELECT tr.object_id FROM $wpdb->term_relationships tr LEFT JOIN $wpdb->term_taxonomy tt ON (tr.term_taxonomy_id = tt.term_taxonomy_id) WHERE tt.term_id IN (" . implode( ', ', array_map( 'intval', $excluded_terms ) ) . ') )'; 
  52.  
  53. // 'post_status' clause depends on the current user. 
  54. if ( is_user_logged_in() ) { 
  55. $user_id = get_current_user_id(); 
  56.  
  57. $post_type_object = get_post_type_object( $post->post_type ); 
  58. if ( empty( $post_type_object ) ) { 
  59. $post_type_cap = $post->post_type; 
  60. $read_private_cap = 'read_private_' . $post_type_cap . 's'; 
  61. } else { 
  62. $read_private_cap = $post_type_object->cap->read_private_posts; 
  63.  
  64. /** 
  65. * Results should include private posts belonging to the current user, or private posts where the 
  66. * current user has the 'read_private_posts' cap. 
  67. */ 
  68. $private_states = get_post_stati( array( 'private' => true ) ); 
  69. $where .= " AND ( p.post_status = 'publish'"; 
  70. foreach ( (array) $private_states as $state ) { 
  71. if ( current_user_can( $read_private_cap ) ) { 
  72. $where .= $wpdb->prepare( " OR p.post_status = %s", $state ); 
  73. } else { 
  74. $where .= $wpdb->prepare( " OR (p.post_author = %d AND p.post_status = %s)", $user_id, $state ); 
  75. $where .= " )"; 
  76. } else { 
  77. $where .= " AND p.post_status = 'publish'"; 
  78.  
  79. $op = $previous ? '<' : '>'; 
  80. $order = $previous ? 'DESC' : 'ASC'; 
  81.  
  82. /** 
  83. * Filters the JOIN clause in the SQL for an adjacent post query. 
  84. * The dynamic portion of the hook name, `$adjacent`, refers to the type 
  85. * of adjacency, 'next' or 'previous'. 
  86. * @since 2.5.0 
  87. * @since 4.4.0 Added the `$taxonomy` and `$post` parameters. 
  88. * @param string $join The JOIN clause in the SQL. 
  89. * @param bool $in_same_term Whether post should be in a same taxonomy term. 
  90. * @param array $excluded_terms Array of excluded term IDs. 
  91. * @param string $taxonomy Taxonomy. Used to identify the term used when `$in_same_term` is true. 
  92. * @param WP_Post $post WP_Post object. 
  93. */ 
  94. $join = apply_filters( "get_{$adjacent}_post_join", $join, $in_same_term, $excluded_terms, $taxonomy, $post ); 
  95.  
  96. /** 
  97. * Filters the WHERE clause in the SQL for an adjacent post query. 
  98. * The dynamic portion of the hook name, `$adjacent`, refers to the type 
  99. * of adjacency, 'next' or 'previous'. 
  100. * @since 2.5.0 
  101. * @since 4.4.0 Added the `$taxonomy` and `$post` parameters. 
  102. * @param string $where The `WHERE` clause in the SQL. 
  103. * @param bool $in_same_term Whether post should be in a same taxonomy term. 
  104. * @param array $excluded_terms Array of excluded term IDs. 
  105. * @param string $taxonomy Taxonomy. Used to identify the term used when `$in_same_term` is true. 
  106. * @param WP_Post $post WP_Post object. 
  107. */ 
  108. $where = apply_filters( "get_{$adjacent}_post_where", $wpdb->prepare( "WHERE p.post_date $op %s AND p.post_type = %s $where", $current_post_date, $post->post_type ), $in_same_term, $excluded_terms, $taxonomy, $post ); 
  109.  
  110. /** 
  111. * Filters the ORDER BY clause in the SQL for an adjacent post query. 
  112. * The dynamic portion of the hook name, `$adjacent`, refers to the type 
  113. * of adjacency, 'next' or 'previous'. 
  114. * @since 2.5.0 
  115. * @since 4.4.0 Added the `$post` parameter. 
  116. * @param string $order_by The `ORDER BY` clause in the SQL. 
  117. * @param WP_Post $post WP_Post object. 
  118. */ 
  119. $sort = apply_filters( "get_{$adjacent}_post_sort", "ORDER BY p.post_date $order LIMIT 1", $post ); 
  120.  
  121. $query = "SELECT p.ID FROM $wpdb->posts AS p $join $where $sort"; 
  122. $query_key = 'adjacent_post_' . md5( $query ); 
  123. $result = wp_cache_get( $query_key, 'counts' ); 
  124. if ( false !== $result ) { 
  125. if ( $result ) 
  126. $result = get_post( $result ); 
  127. return $result; 
  128.  
  129. $result = $wpdb->get_var( $query ); 
  130. if ( null === $result ) 
  131. $result = ''; 
  132.  
  133. wp_cache_set( $query_key, $result, 'counts' ); 
  134.  
  135. if ( $result ) 
  136. $result = get_post( $result ); 
  137.  
  138. return $result;