Функция WP_SET_POST_TERMS() │ WP 2.8.0

Функция WP_SET_POST_TERMS() устанавливает категории и теги для указанной записи (поста) в WordPress.

Зачем это нужно?

Для иерархических таксономий (например, категорий) вам нужно указывать ID термина, а не его название. Это предотвращает возникновение конфликтов, когда разные термины могут иметь одинаковые названия в разных ветвях таксономии.

Вы можете найти ID термина в админ-панели (в URL редактирования термина) или получить его с помощью следующего кода:

$term_id = term_exists( $term, $taxonomy, $parent )['term_id'];

Где используется

• В функции wp_set_object_terms()
• Используется в wp_set_post_categories(), wp_set_post_tags(), set_post_format()

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

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

• false — если $post_id не является числом или равен 0.
• Массив ID — если операция прошла успешно.
• WP_Error — если произошла ошибка.

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

Вот как использовать функцию wp_set_post_terms():

wp_set_post_terms( $post_id, $terms, $taxonomy, $append );

Параметры

• $post_id (int) (обязательный) — ID поста.
• $terms (string/array/int[]) — Список элементов таксономии в виде массива или строки, разделенной запятыми.
• Если таксономия иерархическая, необходимо указывать только ID термина (целое число). Если передать строку, она преобразуется в 0. Это связано с тем, что в иерархических таксономиях могут быть два термина с одинаковым названием.
• Убедитесь, что вы передаете ID как целое число, а не строку. Например, '98' будет воспринято как название термина, а не как его ID. В новых версиях этого бага, похоже, уже нет.

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

• $taxonomy (строка) — Название таксономии, к которой будут привязаны посты. По умолчанию: post_tag.

• $append (логический) — Добавить к существующим терминам или заменить их:

  • true — будет добавлено к существующим;
  • false — заменит существующие.

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

Примеры

1. Установка категорий и тегов по умолчанию

Следующий пример показывает, как установить категорию и тег по умолчанию для новых постов, если они еще не указаны. Этот код можно вставить в functions.php вашего шаблона:

add_action( 'wp_insert_post', 'update_post_terms' );
function update_post_terms( $post_id ) {
if ( $parent = wp_is_post_revision( $post_id ) )
$post_id = $parent;

$post = get_post( $post_id );

if ( $post->post_type != 'post' )
    return;

// Добавляем тег по умолчанию
wp_set_post_terms( $post_id, 'Имя Тега', 'post_tag', true );

// Добавляем категорию по умолчанию
$categories = wp_get_post_categories( $post_id );
$newcat = get_term_by( 'name', 'Имя Категории', 'category' );
array_push( $categories, $newcat->term_id );

wp_set_post_categories( $post_id, $categories );

}

2. Пример работы с иерархическими терминами

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

Чтобы получить ID термина, используйте:

$term_id = term_exists( $term, $taxonomy, $parent );

А затем используйте такой код:

wp_set_post_terms( $post_id, $term_id, $taxonomy );

Примечания

• Обратите внимание на функцию wp_set_object_terms(), которую мы использовали в примерах.

Изменения

• С версии 2.8.0 функция была впервые добавлена в WordPress.

Код функции

Вот как выглядит код функции wp_set_post_terms в WordPress:

function wp_set_post_terms( $post_id = 0, $terms = '', $taxonomy = 'post_tag', $append = false ) {
$post_id = (int) $post_id;

if ( ! $post_id ) {
    return false;
}

if ( empty( $terms ) ) {
    $terms = array();
}

if ( ! is_array( $terms ) ) {
    $comma = _x( ',', 'tag delimiter' );
    if ( ',' !== $comma ) {
        $terms = str_replace( $comma, ',', $terms );
    }
    $terms = explode( ',', trim( $terms, " ntrx0B," ) );
}

if ( is_taxonomy_hierarchical( $taxonomy ) ) {
    $terms = array_unique( array_map( 'intval', $terms ) );
}

return wp_set_object_terms( $post_id, $terms, $taxonomy, $append );

}

Теперь вы знаете, как работает функция WP_SET_POST_TERMS() и как ее можно использовать для управления категориями и тегами в WordPress!