# wp_set_object_terms()

URL: https://chugunov.pro/api-wordpress/functions/wp_set_object_terms/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 2.3.0.

## Сигнатура

```php
wp_set_object_terms( int $object_id, string|int|array $terms, string $taxonomy, bool $append = false ): array|WP_Error
```

## Описание

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

## Параметры

- `$object_id` `int` — обязательный. Объект, с которым нужно установить связь.
- `$terms` `string|int|array` — обязательный. Один слаг термина, один ID термина или массив слагов либо ID терминов.
  
  Заменит все существующие связанные термины в этой таксономии. Передача пустого массива удалит все связанные термины.
- `$taxonomy` `string` — обязательный. Контекст, в котором термин связывается с объектом.
- `$append` `bool` — необязательный, по умолчанию `false`. Если false, удалит разницу терминов.

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

`array|WP_Error` — WP_Error

## Исходный код

Файл: `wp-includes/taxonomy.php:2820`

```php
function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
	global $wpdb;

	$object_id = (int) $object_id;

	if ( ! taxonomy_exists( $taxonomy ) ) {
		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
	}

	if ( empty( $terms ) ) {
		$terms = array();
	} elseif ( ! is_array( $terms ) ) {
		$terms = array( $terms );
	}

	if ( ! $append ) {
		$old_tt_ids = wp_get_object_terms(
			$object_id,
			$taxonomy,
			array(
				'fields'                 => 'tt_ids',
				'orderby'                => 'none',
				'update_term_meta_cache' => false,
			)
		);
	} else {
		$old_tt_ids = array();
	}

	$tt_ids     = array();
	$new_tt_ids = array();

	foreach ( (array) $terms as $term ) {
		if ( '' === trim( $term ) ) {
			continue;
		}

		$term_info = term_exists( $term, $taxonomy );

		if ( ! $term_info ) {
			// Skip if a non-existent term ID is passed.
			if ( is_int( $term ) ) {
				continue;
			}

			$term_info = wp_insert_term( $term, $taxonomy );
		}

		if ( is_wp_error( $term_info ) ) {
			return $term_info;
		}

		$tt_id    = $term_info['term_taxonomy_id'];
		$tt_ids[] = $tt_id;

		if ( $wpdb->get_var( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id = %d", $object_id, $tt_id ) ) ) {
			continue;
		}

		/**
		 * Fires immediately before an object-term relationship is added.
		 *
		 * @since 2.9.0
		 * @since 4.7.0 Added the `$taxonomy` parameter.
		 *
		 * @param int    $object_id Object ID.
		 * @param int    $tt_id     Term taxonomy ID.
		 * @param string $taxonomy  Taxonomy slug.
		 */
		do_action( 'add_term_relationship', $object_id, $tt_id, $taxonomy );

		$wpdb->insert(
			$wpdb->term_relationships,
			array(
				'object_id'        => $object_id,
				'term_taxonomy_id' => $tt_id,
			)
		);

		/**
		 * Fires immediately after an object-term relationship is added.
		 *
		 * @since 2.9.0
		 * @since 4.7.0 Added the `$taxonomy` parameter.
		 *
		 * @param int    $object_id Object ID.
		 * @param int    $tt_id     Term taxonomy ID.
		 * @param string $taxonomy  Taxonomy slug.
		 */
		do_action( 'added_term_relationship', $object_id, $tt_id, $taxonomy );

		$new_tt_ids[] = $tt_id;
	}

	if ( $new_tt_ids ) {
		wp_update_term_count( $new_tt_ids, $taxonomy );
	}

	if ( ! $append ) {
		$delete_tt_ids = array_diff( $old_tt_ids, $tt_ids );

		if ( $delete_tt_ids ) {
			$in_delete_tt_ids = "'" . implode( "', '", $delete_tt_ids ) . "'";
			$delete_term_ids  = $wpdb->get_col( $wpdb->prepare( "SELECT tt.term_id FROM $wpdb->term_taxonomy AS tt WHERE tt.taxonomy = %s AND tt.term_taxonomy_id IN ($in_delete_tt_ids)", $taxonomy ) );
			$delete_term_ids  = array_map( 'intval', $delete_term_ids );

			$remove = wp_remove_object_terms( $object_id, $delete_term_ids, $taxonomy );
			if ( is_wp_error( $remove ) ) {
				return $remove;
			}
		}
	}

	$t = get_taxonomy( $taxonomy );

	if ( ! $append && isset( $t->sort ) && $t->sort ) {
		$values     = array();
		$term_order = 0;

		$final_tt_ids = wp_get_object_terms(
			$object_id,
			$taxonomy,
			array(
				'fields'                 => 'tt_ids',
				'update_term_meta_cache' => false,
			)
		);

		foreach ( $tt_ids as $tt_id ) {
			if ( in_array( (int) $tt_id, $final_tt_ids, true ) ) {
				$values[] = $wpdb->prepare( '(%d, %d, %d)', $object_id, $tt_id, ++$term_order );
			}
		}

		if ( $values ) {
			if ( false === $wpdb->query( "INSERT INTO $wpdb->term_relationships (object_id, term_taxonomy_id, term_order) VALUES " . implode( ',', $values ) . ' ON DUPLICATE KEY UPDATE term_order = VALUES(term_order)' ) ) {
				return new WP_Error( 'db_insert_error', __( 'Could not insert term relationship into the database.' ), $wpdb->last_error );
			}
		}
	}

	wp_cache_delete( $object_id, $taxonomy . '_relationships' );
	wp_cache_set_terms_last_changed();

	/**
	 * Fires after an object's terms have been set.
	 *
	 * @since 2.8.0
	 *
	 * @param int    $object_id  Object ID.
	 * @param array  $terms      An array of object term IDs or slugs.
	 * @param array  $tt_ids     An array of term taxonomy IDs.
	 * @param string $taxonomy   Taxonomy slug.
	 * @param bool   $append     Whether to append new terms to the old terms.
	 * @param array  $old_tt_ids Old array of term taxonomy IDs.
	 */
	do_action( 'set_object_terms', $object_id, $terms, $tt_ids, $taxonomy, $append, $old_tt_ids );

	return $tt_ids;
}
```

## История изменений

- 2.3.0 — Introduced.

## Связанные

Использует: [`wp_cache_set_terms_last_changed`](https://chugunov.pro/api-wordpress/functions/wp_cache_set_terms_last_changed/), [`wp_cache_delete`](https://chugunov.pro/api-wordpress/functions/wp_cache_delete/), [`wp_update_term_count`](https://chugunov.pro/api-wordpress/functions/wp_update_term_count/), [`wp_get_object_terms`](https://chugunov.pro/api-wordpress/functions/wp_get_object_terms/), [`wp_insert_term`](https://chugunov.pro/api-wordpress/functions/wp_insert_term/), [`wp_remove_object_terms`](https://chugunov.pro/api-wordpress/functions/wp_remove_object_terms/), [`term_exists`](https://chugunov.pro/api-wordpress/functions/term_exists/), [`taxonomy_exists`](https://chugunov.pro/api-wordpress/functions/taxonomy_exists/), `wpdb::insert`, `wpdb::get_col`, `wpdb::query`, [`__`](https://chugunov.pro/api-wordpress/functions/__/), [`get_taxonomy`](https://chugunov.pro/api-wordpress/functions/get_taxonomy/), [`do_action`](https://chugunov.pro/api-wordpress/functions/do_action/), `wpdb::get_var`, `wpdb::prepare`, [`is_wp_error`](https://chugunov.pro/api-wordpress/functions/is_wp_error/), `WP_Error::__construct`.
Используется в: `WP_REST_Posts_Controller::handle_terms`, [`media_upload_form_handler`](https://chugunov.pro/api-wordpress/functions/media_upload_form_handler/), [`wp_ajax_save_attachment_compat`](https://chugunov.pro/api-wordpress/functions/wp_ajax_save_attachment_compat/), [`wp_set_link_cats`](https://chugunov.pro/api-wordpress/functions/wp_set_link_cats/), [`wp_add_object_terms`](https://chugunov.pro/api-wordpress/functions/wp_add_object_terms/), [`wp_delete_term`](https://chugunov.pro/api-wordpress/functions/wp_delete_term/), [`wp_set_post_terms`](https://chugunov.pro/api-wordpress/functions/wp_set_post_terms/), [`wp_update_nav_menu_item`](https://chugunov.pro/api-wordpress/functions/wp_update_nav_menu_item/).

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/wp_set_object_terms/