get_ancestors() │ WP 3.1.0

Получает ID родительских элементов указанного объекта (страницы, таксономии, категории).

Важно! Если у текущего объекта нет родителей, то функция вренет пустой массив.

Работает на основе: get_post_ancestors(), get_term()

Основа для: get_term_parents_list()

1 раз — 0.00174 сек (очень медленно) | 50000 раз — 0.95 сек (очень быстро) | PHP 7.2.5, WP 5.0.1

Хуки из функции

get_ancestors

Возвращает

int[].

Массив идентификаторов (ID) родительских элементов, где последняя ячейка массива - это ID самого верхнего элемента.
Пустой массив — когда передан пустой объект или у текущего объекта нет родителей.

Использование

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

$object_id(строка/число) (обязательный): ID дочернего элемента (элемента ID родительских элементов которого надо получить).
$object_type(строка): Название типа объекта, к которому относится элемент. Это может быть название таксономии: post_tag, category ... или название типа записи page, post.
По умолчанию: ''
$resource_type(строка) (WP 4.1): Название типа объекта. Может быть: post_type или taxonomy.
По умолчанию: ''

Примеры

#1 Получим ID всех родительских элементов таксономии

Предположим у нас есть такая структура категорий. В скобках указаны ID:

Книги (6)
- фантастика (23)
  - Рэй Брэдбери (208)

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

Теперь, переменная $ancestors будет содержать в себе такой массив:

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

#2 Получим ID всех родительских страниц

Идентично первому примеру, можно получить ID родительских постоянных страниц, предположим у нас такая структура:

О сайте (447)
- Дочерняя страница (448)

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

Теперь, переменная $ancestors будет содержать в себе массив:

Array
(
	[0] => 447
)

#3 Получим ID самой верхней родительской категории

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

#4 Название верхнего элемента таксономии, к которому привязана запись (пост)

Функция возвращает название самого верхнего термина указанной таксономии, к которому привязана запись (пост).

Если терминов несколько — используется первый (верхний).
Если у термина нет родительских терминов, будет возвращено его собственное название.

В отличие от get_ancestors(), функция всегда получит термин, если он указан для поста.

/**
 * Получает название самого верхнего термина указанной таксономии, к которой привязан пост.
 *
 * @param int|WP_Post|null $post
 * @param string           $tax
 */
function get_post_top_term_name( $post = null, string $tax = 'category' ): string {
	$terms = get_the_terms( $post, $tax );

	if ( empty( $terms ) || is_wp_error( $terms ) ) {
		return '';
	}

	$term     = $terms[0];
	$term_ids = get_ancestors( $term->term_id, $tax );
	$term_id  = $term_ids ? array_pop( $term_ids ) : $term->term_id;

	return get_term( $term_id )->name ?? '';
}

Список изменений

С версии 3.1.0	Введена.
С версии 4.1.0	Introduced the `$resource_type` argument.

Код `get_ancestors() get ancestors` ^{WP 6.9}

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 );
}