get_adjacent_post( bool $in_same_term = false, int[]|string $excluded_terms = '', bool $previous = true, string $taxonomy = 'category' ): WP_Post|null|string

Description

Parameters

$in_same_termbooloptional

Whether post should be in the same taxonomy term. Default false.Default: false

$excluded_termsint[]|stringoptional

Array or comma-separated list of excluded term IDs. Default empty string.Default: ''

$previousbooloptional

Whether to retrieve previous post. Default true.Default: true

$taxonomystringoptional

Taxonomy, if $in_same_term is true. Default 'category'.Default: 'category'

Return

WP_Post|null|string

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

Hooks fired · 4

4 hooks fire while get_adjacent_post() runs, in this order:

1. 1
   apply_filters( get_{$adjacent}_post_excluded_terms )filterline 1879 (+50 into the body)

   Filters the IDs of terms excluded from adjacent post queries.

2. 2
   apply_filters( get_{$adjacent}_post_join )filterline 1964 (+135 into the body)

   Filters the JOIN clause in the SQL for an adjacent post query.

3. 3
   apply_filters( get_{$adjacent}_post_where )filterline 1990 (+161 into the body)

   Filters the WHERE clause in the SQL for an adjacent post query.

4. 4
   apply_filters( get_{$adjacent}_post_sort )filterline 2012 (+183 into the body)

   Filters the ORDER BY clause in the SQL for an adjacent post query.

Uses · 17

• get_post()Retrieves post data given a post ID or post object.
• taxonomy_exists()Determines whether the taxonomy name exists.
• str_contains()Polyfill for `str_contains()` function added in PHP 8.0.
• _deprecated_argument()Marks a function argument as deprecated and inform when it has been used.
• __()Retrieves the translation of $text.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• is_object_in_taxonomy()Determines if the given object type is associated with the given taxonomy.
• wp_get_object_terms()Retrieves the terms associated with the given object(s), in the supplied taxonomies.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• is_user_logged_in()Determines whether the current visitor is a logged in user.
• get_current_user_id()Gets the current user's ID.
• get_post_type_object()Retrieves a post type object by name.

Used by · 7

• get_adjacent_post_link()Retrieves the adjacent post link.
• get_adjacent_post_rel_link()Retrieves the adjacent post relational link.
• get_next_post()Retrieves the next post that is adjacent to the current post.
• get_previous_post()Retrieves the previous post that is adjacent to the current post.
• twentyfifteen_post_nav_background()Adds featured image as background image to post navigation elements.
• twentyfourteen_post_nav()Displays navigation to next/previous post when applicable.
• twentythirteen_post_nav()Displays navigation to next/previous post when applicable.

Source

View on Trac ↗View on GitHub ↗

1829function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previous = true, $taxonomy = 'category' ) {1830	global $wpdb;1831 1832	$post = get_post();1833 1834	if ( ! $post || ! taxonomy_exists( $taxonomy ) ) {1835		return null;1836	}1837 1838	$current_post_date = $post->post_date;1839 1840	$join     = '';1841	$where    = '';1842	$adjacent = $previous ? 'previous' : 'next';1843 1844	if ( ! empty( $excluded_terms ) && ! is_array( $excluded_terms ) ) {1845		// Back-compat, $excluded_terms used to be $excluded_categories with IDs separated by " and ".1846		if ( str_contains( $excluded_terms, ' and ' ) ) {1847			_deprecated_argument(1848				__FUNCTION__,1849				'3.3.0',1850				sprintf(1851					/* translators: %s: The word 'and'. */1852					__( 'Use commas instead of %s to separate excluded terms.' ),1853					"'and'"1854				)1855			);1856			$excluded_terms = explode( ' and ', $excluded_terms );1857		} else {1858			$excluded_terms = explode( ',', $excluded_terms );1859		}1860 1861		$excluded_terms = array_map( 'intval', $excluded_terms );1862	}1863 1864	/**1865	 * Filters the IDs of terms excluded from adjacent post queries.1866	 *1867	 * The dynamic portion of the hook name, `$adjacent`, refers to the type1868	 * of adjacency, 'next' or 'previous'.1869	 *1870	 * Possible hook names include:1871	 *1872	 *  - `get_next_post_excluded_terms`1873	 *  - `get_previous_post_excluded_terms`1874	 *1875	 * @since 4.4.01876	 *1877	 * @param int[]|string $excluded_terms Array of excluded term IDs. Empty string if none were provided.1878	 */1879	$excluded_terms = apply_filters( "get_{$adjacent}_post_excluded_terms", $excluded_terms );1880 1881	if ( $in_same_term || ! empty( $excluded_terms ) ) {1882		if ( $in_same_term ) {1883			$join  .= " INNER JOIN $wpdb->term_relationships AS tr ON p.ID = tr.object_id INNER JOIN $wpdb->term_taxonomy AS tt ON tr.term_taxonomy_id = tt.term_taxonomy_id";1884			$where .= $wpdb->prepare( 'AND tt.taxonomy = %s', $taxonomy );1885 1886			if ( ! is_object_in_taxonomy( $post->post_type, $taxonomy ) ) {1887				return '';1888			}1889			$term_array = wp_get_object_terms( $post->ID, $taxonomy, array( 'fields' => 'ids' ) );1890			if ( is_wp_error( $term_array ) ) {1891				return '';1892			}1893 1894			// Remove any exclusions from the term array to include.1895			$term_array = array_diff( $term_array, (array) $excluded_terms );1896 1897			if ( ! $term_array ) {1898				return '';1899			}1900 1901			$term_array = array_map( 'intval', $term_array );1902 1903			$where .= ' AND tt.term_id IN (' . implode( ',', $term_array ) . ')';1904		}1905 1906		if ( ! empty( $excluded_terms ) ) {1907			$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 ) ) . ') )';1908		}

History

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/link-template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.