Использование функции get_terms() в WordPress с примерами

Функция get_terms() в WordPress используется для получения терминов (категорий, меток и других таксономий) на основе заданных параметров. Она предоставляет мощные возможности для настройки и фильтрации результатов, что позволяет разработчикам легко работать с таксономиями.

get_terms( array|string $args = array(), array|string $deprecated = '' ): WP_Term[]|int[]|string[]|string|WP_Error

Параметры

• $args (array|string, optional): Массив или строка аргументов, которые определяют, какие термины нужно получить. Обязательным является аргумент taxonomy, который указывает название или массив названий таксономий.
• $deprecated (array|string, optional): Устаревший аргумент, использовавшийся до версии 4.5. Если присутствует, будет интерпретирован как $args.

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

• Возвращает массив объектов WP_Term при успешном получении.
• Если термины не найдены, возвращает пустой массив.
• Возвращает WP_Error, если указанная таксономия не существует.

Аргументы параметра $args

Обязательные параметры

• taxonomy (строка/массив)
  Название таксономии, с которой работать. Можно указать несколько названий в виде массива. С версии WP 4.5, до этого названия таксономий указывались в первом параметре самой функции.

Параметры для выборки

• number (число)
  Максимальное количество элементов, которые будут получены (лимит). По умолчанию: все.
• object_ids (число/массив)
  Укажите число или массив чисел, чтобы получить термины, у которых поле object_id таблицы wp_term_relationships совпадает с указанными значениями.
• include (строка/массив)
  ID терминов, которые нужно включить в выборку. Если указать этот параметр, то многие другие станут бесполезными. Парсится через wp_parse_id_list(). По умолчанию: ''.
• exclude (строка/массив)
  ID терминов, которые нужно исключить. Парсится через wp_parse_id_list(). По умолчанию: ''.
• exclude_tree (строка/массив)
  ID родительских терминов, которые нужно исключить. Исключена будет вся ветка. Парсится через wp_parse_id_list(). По умолчанию: ''.
• offset (число)
  Верхний отступ в запросе. Сколько первых элементов пропустить. По умолчанию: без отступов.

Параметры сортировки

• orderby (строка)
  Поле, по которому сортировать результат. Может быть:
  • id или term_id — по ID.
  • name — по названию (по умолчанию).
  • count — по количеству записей.
  • slug — по альтернативному названию.
  • description — по описанию.
  • term_group — по группе.
  • parent — по полю родителя.
  • none — не сортировать.
  По умолчанию: name.
• order (строка)
  Направление сортировки, указанной в параметре orderby:
  • ASC — по порядку, от меньшего к большему.
  • DESC — в обратном порядке, от большего к меньшему.
  По умолчанию: ASC.

Фильтры терминов

• hide_empty (логический)
  Скрывать ли термины, в которых нет записей. 1 (true) — скрывать пустые, 0 (false) — показывать пустые.
  По умолчанию: true.
• fields (строка)
  Какие поля возвращать в результирующем массиве. Может быть:
  • all — вернуть массив объектов (все данные) — по умолчанию.
  • ids — вернуть массив чисел.
  • names — вернуть массив строк.
  • count — возвращает количество найденных терминов.
  По умолчанию: all.
• count (логический)
  true — вернет количество терминов. В этом случае перебивает параметр fields.
  false — вернет массив объектов терминов.

Параметры поиска

• slug (строка/массив)
  Укажите строку или массив строк, чтобы получить термины с указанными ярлыками (слагами).
  По умолчанию: ''.
• hierarchical (логический)
  Включать ли в результат термины, которые имеют не пустые дочерние термины.
  По умолчанию: true.
• search (строка)
  Поиск по названиям термина и его ярлыку. Т.е. запрос выглядит так: LIKE '%search_string%'.
  По умолчанию: ''.
• name (строка/массив)
  Укажите строку или массив строк, чтобы получить термины с указанными названиями.
  По умолчанию: ''.
• name__like (строка)
  Показать термины, в названии которых есть указанная строка.
  По умолчанию: ''.
• description__like (строка)
  Показать термины, в описании которых есть указанная строка.
  По умолчанию: ''.

Параметры иерархии

• pad_counts (логический)
  Если передать true, то число, показывающее количество записей в родительских категориях, будет суммой своих записей и записей из дочерних категорий.
  По умолчанию: false.
• get (строка)
  Если указать all, то будут жёстко отключены параметры: childless, child_of, hide_empty, hierarchical и pad_counts.
  По умолчанию: ''.
• child_of (число)
  ID родительского термина. Вывести элементы таксономии, которые являются дочерними разделами указанного элемента.
  По умолчанию: 0.
• childless (true|false)
  true пропустит (не получит) термины, у которых есть дочерние термины.
  По умолчанию: false.
• parent (число)
  ID родительского термина, чтобы получить только прямых потомков.
  По умолчанию: ''.

Параметры метаданных

• term_taxonomy_id (число/массив)
  Укажите число или массив чисел, чтобы получить термины, у которых поле term_taxonomy_id совпадает с указанными значениями.
  По умолчанию: ''.
• cache_domain (строка)
  Позволяет установить уникальный ключ кэша, который будет использоваться в get_terms().
  По умолчанию: 'core'.
• update_term_meta_cache (логический)
  true — загрузить кэш метаданных, чтобы потом их можно было быстро получить.
  По умолчанию: true.
• meta_query (массив)
  Запрос для получения элементов на основе метаданных. Смотрите WP_Meta_Query.
• meta_key (строка)
  Получит термины, у которых есть указанное метаполе. Можно использовать в связке с meta_value.
  По умолчанию: ''.
• meta_value (строка)
  Получит термины, у которых значение метаполя равно указанному значению. Всегда используется в связке с meta_key.
  По умолчанию: ''.

Прочие параметры

• suppress_filter (логический)
  Подавлять работу фильтров или нет? Если выставить в true, то фильтр get_terms просто не будет работать для текущего запроса терминов.
  По умолчанию: false (фильтры работают).
• cache_results (true|false) (WP 6.4)
  Нужно ли кэшировать результаты в Объектный кэш.
  По умолчанию: true.

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

$terms = get_terms( [
    'taxonomy'   => 'my_taxonomy', // название таксономии
    'hide_empty' => false,          // показывать пустые термины
] );

if ( $terms && ! is_wp_error( $terms ) ) {
    echo '<ul>';
    foreach ( $terms as $term ) {
        echo '<li>' . esc_html( $term->name ) . '</li>';
    }
    echo '</ul>';
}

В этом примере мы получаем список всех терминов таксономии my_taxonomy и выводим их названия в виде списка.

Пример 2: Получение категорий с сортировкой по количеству записей

$my_terms = get_terms( [
    'taxonomy'   => 'category',      // категория
    'orderby'    => 'count',         // сортировка по количеству записей
    'hide_empty' => false,           // показывать пустые категории
] );

if ( $my_terms && ! is_wp_error( $my_terms ) ) {
    foreach ( $my_terms as $term ) {
        echo $term->name . ' (' . $term->count . ')<br>';
    }
}

Здесь мы получаем все категории, отсортированные по количеству записей в каждой, и выводим их названия вместе с количеством записей.

Пример 3: Вывод терминов с разделителем

$terms = get_terms( [
    'taxonomy'   => 'my_term', // название таксономии
    'hide_empty' => false,      // показывать пустые термины
] );

if ( $terms && ! is_wp_error( $terms ) ) {
    $items = [];
    foreach ( $terms as $term ) {
        $items[] = sprintf(
            '<a href="%s" title="%s">%s</a>',
            esc_url( get_term_link( $term ) ),
            esc_attr( sprintf( __( 'View all posts filed under %s', 'my_localization_domain' ), $term->name ) ),
            esc_html( $term->name )
        );
    }
    echo '<p class="my-term-archive">' . implode( ' · ', $items ) . '</p>';
}

Этот код получает все термины из таксономии my_term и выводит их в виде ссылок, разделенных символом ·.

Пример 4: Вывод дочерних терминов текущего термина

$current_term_id = get_queried_object_id();
$child_terms = get_terms( [
    'taxonomy'   => 'my_taxonomy',
    'child_of'   => $current_term_id, // получить дочерние термины
    'hide_empty' => false,
] );

if ( $child_terms && ! is_wp_error( $child_terms ) ) {
    echo '<ul>';
    foreach ( $child_terms as $term ) {
        echo '<li>' . esc_html( $term->name ) . '</li>';
    }
    echo '</ul>';
}

В этом примере мы получаем дочерние термины текущего термина и выводим их в виде списка.

Пример 5: Использование метаполей в запросе

$terms = get_terms( [
    'taxonomy'   => 'my_taxonomy',
    'meta_query' => [
        [
            'key'   => 'custom_field',  // имя метаполя
            'value' => 'value_to_search', // значение для поиска
        ],
    ],
] );

if ( $terms && ! is_wp_error( $terms ) ) {
    foreach ( $terms as $term ) {
        echo $term->name . '<br>';
    }
}

В этом примере мы получаем термины, у которых есть определенное значение в метаполе custom_field.

Заключение

Функция get_terms() — это мощный инструмент для работы с таксономиями в WordPress. Она позволяет гибко управлять выборкой терминов, что делает ее незаменимой для разработчиков, создающих сложные и адаптивные веб-сайты на WordPress. Пользуйтесь параметрами функции для настройки выборки под свои нужды и не забывайте использовать фильтры для изменения результата запроса.