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

## Функция GET_TERMS() │ WP 2.3.0

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

### Изменения в версии 4.5.0

Ранее, до версии 4.5.0, первым параметром функции get_terms() была таксономия или список таксономий. Например:

```php
$terms = get_terms( 'post_tag', [
    'hide_empty' => false,
] );

Начиная с версии 4.5.0, таксономии нужно указывать через аргумент taxonomy в массиве $args:

$terms = get_terms( [
    'taxonomy' => 'post_tag',
    'hide_empty' => false,
] );

С версии 4.6.0 была добавлена класс WP_Term_Query, который позволяет работать с мета-запросами, а функция get_terms() стала оберткой для этого класса.

Фильтры

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

• get_terms — фильтрует результат (список найденных терминов).
• list_terms_exclusions — позволяет исключать термины, принимает список всех исключенных терминов.
• get_terms_orderby — фильтрует часть запроса ORDER BY.

Возврат значений

Функция get_terms() может вернуть:

• Массив объектов WP_Term — при успехе.
• Пустой массив array() — когда термины не найдены.
• WP_Error — если хотя бы одна из указанных таксономий не существует.
• Число найденных терминов (в виде строки) — когда задан аргумент fields с значением count.

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

Вот пример использования функции get_terms():

$args = [
    'taxonomy'      => [ 'post_tag', 'my_tax' ], // название таксономии
    'orderby'       => 'id',
    'order'         => 'ASC',
    'hide_empty'    => true,
    'object_ids'    => null,
    'include'       => [],
    'exclude'       => [],
    'exclude_tree'  => [],
    'number'        => '',
    'fields'        => 'all',
    'count'         => false,
    'slug'          => '',
    'parent'        => '',
    'hierarchical'  => true,
    'child_of'      => 0,
    'get'           => '', // укажите 'all' для получения всех терминов
    'name__like'    => '',
    'pad_counts'    => false,
    'offset'        => '',
    'search'        => '',
    'cache_domain'  => 'core',
    'name'          => '',    // для получения терминов по имени
    'childless'     => false, // true - пропустить термины с дочерними терминами
    'update_term_meta_cache' => true,
    'meta_query'    => '',
];

$terms = get_terms( $args );

foreach( $terms as $term ){
    print_r( $term );
}

Параметры $args

Для полного списка параметров обратитесь к методу WP_Term_Query::__construct().

Вот основные параметры, которые можно указать:

• taxonomy (string/array) (обязательный) — название таксономии.
• number (int) — максимальное количество элементов, которые будут получены.
• object_ids (int/array) — для получения терминов, соответствующих указанным ID.
• include (string/array) — массив ID терминов, которые нужно включить в выборку.
• exclude (string/array) — массив ID терминов, которые нужно исключить.
• offset (int) — сколько первых строк пропустить в SQL-запросе.
• orderby (string) — поле для сортировки результата.
• order (string) — направление сортировки (ASC или DESC).
• hide_empty (true/false) — скрывать ли термины без записей.

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

1. Получение массива всех категорий

Этот код получит все категории, отсортированные по количеству записей в каждой, включая пустые:

$myterms = get_terms( 'taxonomy=category&orderby=count&hide_empty=0' );

2. Отображение списка имен всех терминов таксономии

Пример вывода имен всех терминов таксономии my_taxonomy:

$terms = get_terms( 'my_taxonomy' );

if( $terms && ! is_wp_error( $terms ) ){
    echo '
';

    foreach( $terms as $term ){
        echo '
'. esc_html( $term->name ) .'
';
    }

    echo '
';
}

3. Отображение категорий, разделенных точкой

Пример того, как отобразить категории, соединенные разделителем ·:

$terms = get_terms( [
    'taxonomy'   => 'my_term',
    'hide_empty' => false,
] );

if( $terms && ! is_wp_error( $terms ) ){
    $items = [];

    foreach( $terms as $term ){
        $items[] = sprintf( 
            '' . esc_html( $term->name ) . '', 
            esc_url( get_term_link( $term ) ),
            esc_attr( sprintf( __( 'Смотреть все записи под %s', 'my_localization_domain' ), $term->name ) )
        );
    }

    echo sprintf( '
%s
', implode( ' · ', $items ) );
}

Изменения

• С версии 2.3.0 - Функция была введена.
• С версии 4.2.0 - Добавлены параметры name и childless.
• С версии 4.4.0 - Введена возможность передавать term_id как алиас для параметра id и добавлены параметры meta_query и update_term_meta_cache.
• С версии 4.5.0 - Изменен формат передачи аргументов.

Таксономии (категории, теги и т.д.) в WordPress помогают организовать содержимое на вашем сайте, и функция get_terms() — это полезный инструмент для работы с ними.