wp_remove_object_terms()
云策文档标注
概述
wp_remove_object_terms() 函数用于从指定对象中移除一个或多个分类法术语。它接受对象ID、术语和分类法名称作为参数，并返回操作结果。
关键要点
- 参数：$object_id（整数，必需）为对象ID；$terms（字符串、整数或数组，必需）为要移除的术语的slug或ID；$taxonomy（字符串，必需）为分类法名称。
- 返回值：成功时返回true，失败时返回false或WP_Error。
- 内部处理：验证分类法存在，将$terms转换为数组，通过term_exists()检查术语，使用term_taxonomy_id进行数据库删除操作。
- 钩子：触发delete_term_relationships和deleted_term_relationships动作，允许开发者在关系删除前后执行自定义代码。
- 缓存清理：移除相关缓存并更新术语计数。
代码示例
// 从帖子中移除标签
wp_remove_object_terms( $post_id, 'sweet', 'post_tag' );
// 使用术语名称数组移除多个标签
$post_tags = array(
'Tag name',
'Another tag name',
);
wp_remove_object_terms( $post_id, $post_tags, 'post_tag' );注意事项
- 函数自WordPress 3.6.0版本引入。
- 如果传递不存在的术语ID，函数会跳过该术语；但传递不存在的术语slug可能导致错误。
- 相关函数包括wp_set_object_terms()、wp_delete_object_term_relationships()和wp_delete_term()。
原文内容
Removes term(s) associated with a given object.
Parameters
$object_idintrequired-
The ID of the object from which the terms will be removed.
$termsstring|int|arrayrequired-
The slug(s) or ID(s) of the term(s) to remove.
$taxonomystringrequired-
Taxonomy name.
Source
function wp_remove_object_terms( $object_id, $terms, $taxonomy ) {
global $wpdb;
$object_id = (int) $object_id;
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
if ( ! is_array( $terms ) ) {
$terms = array( $terms );
}
$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;
}
}
if ( is_wp_error( $term_info ) ) {
return $term_info;
}
$tt_ids[] = $term_info['term_taxonomy_id'];
}
if ( $tt_ids ) {
$in_tt_ids = "'" . implode( "', '", $tt_ids ) . "'";
/**
* Fires immediately before an object-term relationship is deleted.
*
* @since 2.9.0
* @since 4.7.0 Added the `$taxonomy` parameter.
*
* @param int $object_id Object ID.
* @param array $tt_ids An array of term taxonomy IDs.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'delete_term_relationships', $object_id, $tt_ids, $taxonomy );
$deleted = $wpdb->query( $wpdb->prepare( "DELETE FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id IN ($in_tt_ids)", $object_id ) );
wp_cache_delete( $object_id, $taxonomy . '_relationships' );
wp_cache_set_terms_last_changed();
/**
* Fires immediately after an object-term relationship is deleted.
*
* @since 2.9.0
* @since 4.7.0 Added the `$taxonomy` parameter.
*
* @param int $object_id Object ID.
* @param array $tt_ids An array of term taxonomy IDs.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'deleted_term_relationships', $object_id, $tt_ids, $taxonomy );
wp_update_term_count( $tt_ids, $taxonomy );
return (bool) $deleted;
}
return false;
}
Hooks
- do_action( ‘deleted_term_relationships’, int $object_id, array $tt_ids, string $taxonomy )
-
Fires immediately after an object-term relationship is deleted.
- do_action( ‘delete_term_relationships’, int $object_id, array $tt_ids, string $taxonomy )
-
Fires immediately before an object-term relationship is deleted.
Changelog
| Version | Description |
|---|---|
| 3.6.0 | Introduced. |
Skip to note 3 content
Codex
Example
Remove tag from post.
wp_remove_object_terms( $post_id, 'sweet', 'post_tag' );Skip to note 4 content
Tunn
Even though it’s not specified, I found that $terms can also be the names of terms.
$post_tags = array( 'Tag name', 'Another tag name', ); wp_remove_object_terms( $post_id, $post_tags, 'post_tag' );