Функция get_term_parents_list() в WordPress: родительские элементы термина

# Функция GET_TERM_PARENTS_LIST() │ WP 4.8.0

Функция get_term_parents_list() позволяет получить список родительских элементов для заданного термина (элемента таксономии). 

Результат будет содержать текст или ссылки, разделенные указанным разделителем (например, запятой или слешем).

**Использует:** get_ancestors()  
**Используется в:** get_category_parents()

Производительность: 
- 1 раз — 0.003063 сек (очень медленно) 
- 50000 раз — 14.40 сек (медленно)  
- PHP 7.1.2, WP 4.8

**Хуки:** отсутствуют.

## Возвращаемое значение

Функция возвращает String|WP_Error:

- Строка, содержащая slug (унникальный ярлык) или имена терминов, разделенные запятой.
- HTML-код с ссылками на термины, привязанными к их именам.
- Пустую строку, если термин не существует.
- WP_Error, если такая таксономия не существует.

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

```php
get_term_parents_list( $term_id, $taxonomy, $args );

• $term_id (int) (обязательный) — ID термина.
• $taxonomy (string) (обязательный) — название таксономии.
• $args (string|array) — массив дополнительных аргументов. По умолчанию он выглядит следующим образом:

$defaults = [
    'format'    => 'name',
    'separator' => '/',
    'link'      => true,
    'inclusive' => true,
];

Параметры по умолчанию

• format (string): Используйте имена терминов или slug для отображения. Допустимые значения:

  • 'name' — отображает имена терминов.
  • 'slug' — отобр��жает slug терминов.
  • По умолчанию: 'name'.

• separator (string): Разделитель между именами или ссылками (если параметр link установлен).

  • По умолчанию: '/'.

• link (true|false): Форматировать как ссылку?

  • true — выводит имена как ссылки на термины.
  • false — выводит имена как простой текст.
  • По умолчанию: true.

• inclusive (true|false): Включать ли сам термин в список родителей?

  • По умолчанию: true.

Примеры

Пример 0

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

Этот пример выводит "хлебные крошки" для термина с ID 593 (категории). Элемент сам также включен в цепочку ссылок.

echo get_term_parents_list( 593, 'wpfunccat', [
    'separator' => ' / ',
] );

/*
Taxonomy /
Categories /
*/

Пример 1

Если в параметрах указан link = false:

echo get_term_parents_list( 593, 'wpfunccat', array(
    'separator' => ' / ',
    'link' => false,
) );

/*
Taxonomies / Categories /
*/

Пример 2

Если в параметрах указан format = 'slug':

echo get_term_parents_list( 593, 'wpfunccat', array(
    'separator' => ' / ',
    'format' => 'slug',
    'link' => false,
) );

/*
taxonomy / categories
*/

Подробности о реализации

Вот код функции get_term_parents_list() из файла wp-includes/category-template.php:

function get_term_parents_list( $term_id, $taxonomy, $args = array() ) {
$list = '';
$term = get_term( $term_id, $taxonomy );

if ( is_wp_error( $term ) ) {
    return $term;
}

if ( ! $term ) {
    return $list;
}

$term_id = $term->term_id;

$defaults = array(
    'format'    => 'name',
    'separator' => '/',
    'link'      => true,
    'inclusive' => true,
);

$args = wp_parse_args( $args, $defaults );

foreach ( array( 'link', 'inclusive' ) as $bool ) {
    $args[ $bool ] = wp_validate_boolean( $args[ $bool ] );
}

$parents = get_ancestors( $term_id, $taxonomy, 'taxonomy' );

if ( $args['inclusive'] ) {
    array_unshift( $parents, $term_id );
}

foreach ( array_reverse( $parents ) as $term_id ) {
    $parent = get_term( $term_id, $taxonomy );
    $name   = ( 'slug' === $args['format'] ) ? $parent->slug : $parent->name;

    if ( $args['link'] ) {
        $list .= '' . $name . '' . $args['separator'];
    } else {
        $list .= $name . $args['separator'];
    }
}

return $list;

}

Похожие функции

• get_the_term_list() — позволяет получить список терминов для поста.
• wp_dropdown_categories() — отображает выпадающий список категорий.
• wp_dropdown_pages() — отображает выпадающий список страниц.
• wp_dropdown_users() — отображает выпадающий список пользователей.
• wp_get_archives() — выводит архивы по месяцам, годам и т.д.
• wp_list_categories() — выводит категории в виде списка.
• wp_list_comments() — выводит комментарии в виде списка.
• wp_page_menu() — выводит меню страниц.

Теперь вы знаете, как использовать функцию get_term_parents_list() в WordPress, чтобы получать и отображать родительские элементы для разных терминов.