Функция GET_THE_TERMS() в WordPress: использование, примеры, возвращаемые значения

# Функция GET_THE_TERMS() в WordPress

## Что делает функция?

Функция get_the_terms() позволяет получить элементы таксономии (термины), которые связаны с определённым постом. 

### Как использовать функцию

Эту функцию можно использовать внутри цикла (The Loop), или передать ей ID поста, для которого вы хотите получить термины. Функция работает аналогично функции wp_get_object_terms(), но имеет дело с кэшом и предоставляет фильтр get_the_terms. Она вернёт только те термины, которые отмечены на странице редактирования поста.

![Пример работы функции](assets/uploads/2022/01/clipboard-image-181719.png)

### Время выполнения
- 1 раз — 0.005139 сек (очень медленно)
- 50000 раз — 1.66 сек (быстро)

PHP 7.1.2, WP 4.8

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

Функция может вернуть:
- **Массив** объектов WP_Term — если всё прошло успешно.
- **false** — если термины не найдены или пост не существует.
- **WP_Error** — в других случаях.

Пример возвращаемого массива:

```php
Array (
    [0] => WP_Term Object (
        [term_id] => 30
        [name] => Others
        [slug] => others
        [term_group] => 0
        [term_taxonomy_id] => 30
        [taxonomy] => category
        [description] =>
        [parent] => 3
        [count] => 21
        [filter] => raw
        [term_order] => 7
    )
    [1] => stdClass Object ( ... )
    [2] => stdClass Object ( ... )
    ...
)

Использование функции

Чтобы использовать функцию, необходимо передать два параметра:

get_the_terms( $post, $taxonomy );

• $post (int|WP_Post) (обязательный) — ID поста или объект поста.
• $taxonomy (string) (обязательный) — имя таксономии.

Примеры использования

Пример 1: Получить только первый термин

Представим, что нам нужно получить данные только одного термина:

$terms = get_the_terms( $post, 'my_tax' );
if( $terms ){
    $term = array_shift( $terms ); // получаем первый термин

    // отображаем имя термина
    echo $term->name;
}

Пример 2: Отобразить ссылки на элемент�� таксономии 'my_tax', связанные с постом 10

$cur_terms = get_the_terms( 10, 'my_tax' );
if( is_array( $cur_terms ) ){
    foreach( $cur_terms as $cur_term ){
        echo ''. $cur_term->name .',';
    }
}

Также это можно сделать внутри цикла:

$cur_terms = get_the_terms( $post, 'my_tax' );
if( is_array( $cur_terms ) ){
    foreach( $cur_terms as $cur_term ){
        echo ''. $cur_term->name .',';
    }
}

Пример 3: Получить верхний уровень термина для заданного поста

Создадим кастомную функцию на базе get_the_terms(), чтобы получить верхний уровень термина:

/**
 * Получает верхний уровень термина для заданного поста в цикле.
 *
 * @param string $taxonomy
 * @param int|object $post_id ID или объект поста
 *
 * @return string/wp_error Объект термина или false
 */
function get_top_term( $taxonomy, $post_id = 0 ){
    if( isset($post_id->ID) ) $post_id = $post_id->ID;
    if( ! $post_id )          $post_id = get_the_ID();

    $terms = get_the_terms( $post_id, $taxonomy );

    if( ! $terms || is_wp_error($terms) )
        return $terms;

    // получаем только первый термин
    $term = array_shift( $terms );

    // находим верхний уровень
    $parent_id = $term->parent;
    while( $parent_id ){
        $term = get_term_by( 'id', $parent_id, $term->taxonomy );
        $parent_id = $term->parent;
    }

    return $term;
}

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

$top_term = get_top_term( 'category' );
echo $top_term->name;

Что нового?

Функция была введена в версии 2.5.0.

Код функции

Функция get_the_terms находится в файле wp-includes/category-template.php:

function get_the_terms( $post, $taxonomy ) {
    $post = get_post( $post );

    if ( ! $post ) {
        return false;
    }

    $terms = get_object_term_cache( $post->ID, $taxonomy );

    if ( false === $terms ) {
        $terms = wp_get_object_terms( $post->ID, $taxonomy );
        if ( ! is_wp_error( $terms ) ) {
            $term_ids = wp_list_pluck( $terms, 'term_id' );
            wp_cache_add( $post->ID, $term_ids, $taxonomy . '_relationships' );
        }
    }

    $terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy );

    if ( empty( $terms ) ) {
        return false;
    }

    return $terms;
}

Связанные функции

Некоторые другие функции, связанные с терминами таксономии:

• category_exists()
• get_term()
• get_term_by()
• get_terms()
• has_term()
• wp_set_object_terms()