get_ancestors() │ WP 3.1.0

Gets the IDs of the parent elements of the specified object (page, taxonomy, category).

Uses: get_post_ancestors(), get_term()

Used By: get_term_parents_list()

1 time — 0.00174 sec (very slow) | 50000 times — 0.95 sec (very fast) | PHP 7.2.5, WP 5.0.1

Hooks from the function

get_ancestors

Returns

Int[]. An array of identifiers (IDs) of the parent elements, where the last cell of the array will contain the ID of the topmost element in the chain. Or an empty array.

Usage

get_ancestors( $object_id, $object_type, $resource_type );

$object_id(string/int) (required): The ID of the child element (the element whose parent IDs need to be retrieved).
$object_type(string): The name of the object type to which the element belongs. This can be the name of a taxonomy: post_tag, category ... or the name of a post type page, post.
Default: ''
$resource_type(string) (WP 4.1): The name of the object type. Can be: post_type or taxonomy.
Default: ''

Examples

#1 Get the IDs of all parent elements of the taxonomy term

Suppose we have this category structure. The IDs are in brackets:

Books (6)
- fiction (23)
  - Ray Bradbury (208)

$ancestors = get_ancestors( 208, 'category' );

Now, the variable $ancestors will contain such an array:

Array
(
	[0] => 23
	[1] => 6
)

#2 Get the IDs of all parent pages

Suppose, you need to get the IDs of the parent static pages, let's assume we have this structure:

About site (447)
- Subsidiary page (448)

$ancestors = get_ancestors( 448, 'page' );

Now, the variable $ancestors will contain an array:

Array
(
	[0] => 447
)

#3 Get the ID of the topmost parent category

$ancestors = get_ancestors( 208, 'category' );
$top_cat_id = array_pop( $ancestors );

Changelog

Since 3.1.0	Introduced.
Since 4.1.0	Introduced the `$resource_type` argument.

`get_ancestors() get ancestors` code ^{WP 7.0}

wp-includes/taxonomy.php

function get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' ) {
	$object_id = (int) $object_id;

	$ancestors = array();

	if ( empty( $object_id ) ) {

		/** This filter is documented in wp-includes/taxonomy.php */
		return apply_filters( 'get_ancestors', $ancestors, $object_id, $object_type, $resource_type );
	}

	if ( ! $resource_type ) {
		if ( is_taxonomy_hierarchical( $object_type ) ) {
			$resource_type = 'taxonomy';
		} elseif ( post_type_exists( $object_type ) ) {
			$resource_type = 'post_type';
		}
	}

	if ( 'taxonomy' === $resource_type ) {
		$term = get_term( $object_id, $object_type );
		while ( ! is_wp_error( $term ) && ! empty( $term->parent ) && ! in_array( $term->parent, $ancestors, true ) ) {
			$ancestors[] = (int) $term->parent;
			$term        = get_term( $term->parent, $object_type );
		}
	} elseif ( 'post_type' === $resource_type ) {
		$ancestors = get_post_ancestors( $object_id );
	}

	/**
	 * Filters a given object's ancestors.
	 *
	 * @since 3.1.0
	 * @since 4.1.1 Introduced the `$resource_type` parameter.
	 *
	 * @param int[]  $ancestors     An array of IDs of object ancestors.
	 * @param int    $object_id     Object ID.
	 * @param string $object_type   Type of object.
	 * @param string $resource_type Type of resource $object_type is.
	 */
	return apply_filters( 'get_ancestors', $ancestors, $object_id, $object_type, $resource_type );
}