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

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

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 value

WP_Post|null|string

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

Performance profile

How much work a call to get_adjacent_post() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->get_var().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

10–244

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 310.

Plugin surface

4 hooks

Third-party callbacks on 'get_{$adjacent}_post_excluded_terms', 'get_{$adjacent}_post_join', 'get_{$adjacent}_post_where' run inside this call, and their cost is not bounded by anything here.

Called by

7

7 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• querycontent queryget_post()called directly
• hookthird-party callbacksapply_filters()called directly
• cacheobject cachewp_cache_get_last_changed()called directly
• sqldatabase query->get_var()called directly

Further down the call graph this can also reach option, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 68 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost get_adjacent_post() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters 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 code

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		}

Changelog

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.0.4 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.