WP_SET_OBJECT_TERMS() │ WP 2.3.0

Функция, которая создает связи между объектами и терминами.

Функция связывает объект (например, запись или ссылку) с определенным термином и таксономией. Если связь еще не существует, она будет создана. Также будет создан термин, если он еще не существует (используя его слаг).

Что такое связь?

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

Используется в:

Функция wp_set_post_terms()

Хуки функции

• add_term_relationship
• added_term_relationship
• set_object_terms

Возврат

Функция возвращает массив идентификаторов таксономии термина или WP_Error, если произошла ошибка.

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

wp_set_object_terms( $object_id, $terms, $taxonomy, $append );

Параметры:

• $object_id (int) (обязательный): идентификатор объекта, с которым нужно связать термин.
• $terms (string|int|array) (обязательный): один слаг термина, один идентификатор термина или массив слагов или идентификаторов термина. Замещает все существующие связанные термины в этой таксономии. Если передать пустой массив, будут удалены все связанные термины.
• $taxonomy (string) (обязательный): contexto, в котором нужно связать термин с объектом.
• $append (true|false): если равно false, то удаляет старые термины. По умолчанию false.

Примеры

Пример 1: Добавление записи в указанные категории

Пример показывает, как добавить запись с идентификатором 42 в категории с идентификаторами 6 и 8:

$cat_ids = array( 6, 8 );
// Убедитесь, что переданные идентификаторы категорий — это числа:
// $cat_ids = array_map( 'intval', $cat_ids );
wp_set_object_terms( 42, $cat_ids, 'category' );

Если идентификаторы терминов заданы как строки, функция создаст категории с этими названиями и привяжет запись к терминам.

Пример 2: Удаление записи из всех категорий

Если вы хотите удалить запись с идентификатором 42 из всех категорий (включая категорию по умолчанию):

wp_set_object_terms( 42, NULL, 'category' );

Пример 3: Будьте осторожны при добавлении существующих терминов к объекту!

Второй параметр $terms (например, идентификатор категории) должен быть типа integer или массивом integer.

Примечание: Если вы передадите строковое значение для $terms, WordPress создаст новый термин с именем, соответствующим значению $terms, и не выберет существующий термин по идентификатору. Это происходит потому, что $terms должен быть integer или массивом integers.

$post_id = 15;
$category_id = '14';
$taxonomy = 'category';

// Неправильно:
wp_set_object_terms( $post_id, $category_id, $taxonomy );

// Правильно:
wp_set_object_terms( $post_id, (int) $category_id, $taxonomy );

Пример 4: Создание тегов и добавление записи в них

Этот пример добавляет запись с идентификатором 54 в теги tag1 и tag2. Если таких тегов нет, они будут созданы:

wp_set_object_terms( 54, [ 'tag1', 'tag2' ], 'post_tag' );

Пример 5: Более строгая функция для установки терминов для записи

Чтобы избежать создания нового термина, если он не существует, разработайте собственную функцию:

/**
 * Устанавливает указанные термины для выбранных записей.
 * Обертка для wp_set_object_terms() с строгим поведением, требующим только идентификаторы термов.
 *
 * @param int       $post_id
 * @param int[]|int $term_ids
 * @param bool      $append
 *
 * @return int[]|WP_Error
 */
function strict_set_post_terms( $post_id, $term_ids, $append = true ){
    $post_id = (int) $post_id;
    $term_ids = array_filter( array_map( 'intval', (array) $term_ids ) );

    if( ! $post_id ){
        return new WP_Error( 'error', 'Недействительный или отсутствующий идентификатор записи.' );
    }
    if( ! $term_ids ){
        return new WP_Error( 'error', 'Не предоставлены действительные идентификаторы терминов.' );
    }

    $taxonomy = '';

    // Проверяем термины
    foreach( $term_ids as $index => $term_id ){
        $term = get_term( $term_id );
        if( ! $term ){
            unset( $term_ids[ $index ] );
            continue; // пропускаем недействительные термины
        }

        if( $taxonomy && $taxonomy !== $term->taxonomy ){
            return new WP_Error( 'error', 'Указаны термины из разных таксономий.' );
        }
        $taxonomy = $term->taxonomy;
    }

    if( ! $term_ids ){
        return new WP_Error( 'error', 'Не предоставлены действительные идентификаторы терминов.' );
    }

    $result = wp_set_object_terms( $post_id, $term_ids, $taxonomy, $append );

    if( ! is_wp_error( $result ) ){
        $result = array_map( 'intval', $result );
    }

    return $result;
}

Примечания

• Глобальный объект базы данных WordPress: $wpdb

Изменения

• С версии 2.3.0 — в функции были внесены изменения.

Это упрощенная версия оригинальной статьи о функции wp_set_object_terms(), сделанная доступной и понятной для начинающих пользователей WordPress.