wp_remove_object_terms() │ WP 3.6.0

Breaks the connection between the specified object and the specified term, i.e., removes the post from the taxonomy element (category).

After the connection is removed, the number of posts in the term is recalculated using wp_update_term_count().

Use wp_delete_object_term_relationships() to remove all connections of the object with the taxonomy at once.

Right before the connection is removed, the action delete_term_relationships is triggered, and immediately after the removal, deleted_term_relationships is triggered. The actions pass the variables: $object_id - ID of the processed object and $tt_ids - IDs of the taxonomy terms (these are not the term IDs) whose connection is being broken.

Uses: term_exists()
Used By: wp_delete_object_term_relationships()
Hooks from the function

Returns

true|false|WP_Error.

  • true - if the connection was successfully broken.
  • false or WP_Error object - in case of failure.

Usage

wp_remove_object_terms( $object_id, $terms, $taxonomy );
$object_id(integer) (required)
ID of the object to be removed from the terms. The object refers to any post: post, page, link, custom post type.
$terms(string/array/integer/object) (required)

ID/slug/object of the term from which the specified object in $object_id will be removed. Multiple terms can be specified in an array at once.

If an ID is specified, the value must be of type "integer", not a string in the form of a number. For example 12 not '12'. The values specified here are passed to term_exists() - see there for more details.

$taxonomy(string/array) (required)
Name of the taxonomy in which the terms are located. A string or an array of strings of several taxonomies can be specified.

Examples

0

#1 Removing tags from a post

An example showing how to remove a post from a post_tag taxonomy term:

$post_id  = 5;
$terms    = 'sweet';
$taxonomy = 'post_tag';

$done = wp_remove_object_terms( $post_id, $terms, $taxonomy );

if( $done ){
	echo "Tag posts deleted.";
}
else {
	echo "Failed to delete the tag.";
}

Notes

  • Global. wpdb. $wpdb WordPress database abstraction object.

Changelog

Since 3.6.0 Introduced.

wp_remove_object_terms() code WP 6.8.1

wp-includes/taxonomy.php 
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;
}

For posts