Функция get_term_by() в WordPress

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

Важно: Значение $value не экранировано для поля 'name'. Если это необходимо, вам нужно будет сделать это самостоятельно.

По умолчанию поле $field — это 'id', поэтому можно также использовать null, но это не рекомендуется.

Если значение $value не существует, функция вернет false. Если указаны комбинации $taxonomy, $field и $value, то вернется соответствующий термин.

Эта функция всегда возвращает первый термин, соответствующий комбинации $field, $value и $taxonomy, указанным в параметрах. Если вашей выборке может соответствовать более одного термина (например, когда $field — это 'name'), рассмотрите возможность использования функции get_terms(). Так вы получите все совпадающие термины и сможете сами решить, какой из них вам нужен.

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

get_term_by( $field, $value, $taxonomy, $output, $filter );

Параметры

• $field (string) (обязательный) — Это может быть одно из значений: 'slug', 'name', 'term_id' (или 'id', 'ID'), либо 'term_taxonomy_id'.

• $value (string|int) (обязательный) — Значение термина, по которому идет поиск.

• $taxonomy (string) — Название таксономии. Этот параметр является необязательным, если $field равен 'term_taxonomy_id'. По умолчанию — ''.

• $output (string) — Требуемый тип возвращаемых данных. Один из значений: OBJECT, ARRAY_A или ARRAY_N, которые соответствуют объекту WP_Term, ассоциативному массиву или числовому массиву соответственно. По умолчанию — OBJECT.

• $filter (string) — Способ очистки полей термина. По умолчанию — 'raw'.

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

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

• WP_Term | Array | false — экземпляр WP_Term (или массив) при успешном выполнении. false, если $taxonomy не существует или термин не был найден.

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

Пример 1: Получение термина по имени

// Получим категорию "Новости" по имени:
$term = get_term_by('name', 'Новости', 'category');

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

// Получим теги (таксономия post_tag) по слагу
$term = get_term_by('slug', 'my-tag-name', 'post_tag');

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

// Получим термин "Новости" из таксономии "my_custom_taxonomy" по имени
$term = get_term_by('name', 'Новости', 'my_custom_taxonomy');

Пример 4: Получение термина по его ID

// Получение термина по ID из таксономии 'category'.
$term = get_term_by('id', 12, 'category');

Обратите внимание

Рекомендуется использовать функцию get_term() для получения термина по ID.

В результате приведенных выше примеров переменная $term будет содержать такой объект:

stdClass Object
(
    [term_id] => 80
    [name] => Моя категория
    [slug] => my-category
    [term_group] => 0
    [term_taxonomy_id] => 87
    [taxonomy] => my_tax
    [description] =>
    [parent] => 0
    [count] => 5
)

Замечания

• Учтите, что в версии WordPress 4.1 до 4.3 теперь возможно, что несколько терминов могут соответствовать заданным параметрам имени или слага.
• Если есть возможность, что несколько терминов имеют одинаковое имя или слаг, рекомендуется использовать get_terms() вместо get_term_by().

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