update_term_meta - Documentation

WordPress Version: 5.5

/**
 * Updates term metadata.
 *
 * Use the `$prev_value` parameter to differentiate between meta fields with the same key and term ID.
 *
 * If the meta field for the term does not exist, it will be added.
 *
 * @since 4.4.0
 *
 * @param int    $term_id    Term ID.
 * @param string $meta_key   Metadata key.
 * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
 * @param mixed  $prev_value Optional. Previous value to check before updating.
 *                           If specified, only update existing metadata entries with
 *                           this value. Otherwise, update all entries. Default empty.
 * @return int|bool|WP_Error Meta ID if the key didn't exist. true on successful update,
 *                           false on failure or if the value passed to the function
 *                           is the same as the one that is already in the database.
 *                           WP_Error when term_id is ambiguous between taxonomies.
 */
function update_term_meta($term_id, $meta_key, $meta_value, $prev_value = '')
{
    if (wp_term_is_shared($term_id)) {
        return new WP_Error('ambiguous_term_id', __('Term meta cannot be added to terms that are shared between taxonomies.'), $term_id);
    }
    return update_metadata('term', $term_id, $meta_key, $meta_value, $prev_value);
}

WordPress Version: 5.0

/**
 * Updates term metadata.
 *
 * Use the `$prev_value` parameter to differentiate between meta fields with the same key and term ID.
 *
 * If the meta field for the term does not exist, it will be added.
 *
 * @since 4.4.0
 *
 * @param int    $term_id    Term ID.
 * @param string $meta_key   Metadata key.
 * @param mixed  $meta_value Metadata value.
 * @param mixed  $prev_value Optional. Previous value to check before removing.
 * @return int|WP_Error|bool Meta ID if the key didn't previously exist. True on successful update.
 *                           WP_Error when term_id is ambiguous between taxonomies. False on failure.
 */
function update_term_meta($term_id, $meta_key, $meta_value, $prev_value = '')
{
    if (wp_term_is_shared($term_id)) {
        return new WP_Error('ambiguous_term_id', __('Term meta cannot be added to terms that are shared between taxonomies.'), $term_id);
    }
    return update_metadata('term', $term_id, $meta_key, $meta_value, $prev_value);
}

WordPress Version: 4.4

/**
 * Updates term metadata.
 *
 * Use the `$prev_value` parameter to differentiate between meta fields with the same key and term ID.
 *
 * If the meta field for the term does not exist, it will be added.
 *
 * @since 4.4.0
 *
 * @param int    $term_id    Term ID.
 * @param string $meta_key   Metadata key.
 * @param mixed  $meta_value Metadata value.
 * @param mixed  $prev_value Optional. Previous value to check before removing.
 * @return int|WP_Error|bool Meta ID if the key didn't previously exist. True on successful update.
 *                           WP_Error when term_id is ambiguous between taxonomies. False on failure.
 */
function update_term_meta($term_id, $meta_key, $meta_value, $prev_value = '')
{
    // Bail if term meta table is not installed.
    if (get_option('db_version') < 34370) {
        return false;
    }
    if (wp_term_is_shared($term_id)) {
        return new WP_Error('ambiguous_term_id', __('Term meta cannot be added to terms that are shared between taxonomies.'), $term_id);
    }
    $updated = update_metadata('term', $term_id, $meta_key, $meta_value, $prev_value);
    // Bust term query cache.
    if ($updated) {
        wp_cache_set('last_changed', microtime(), 'terms');
    }
    return $updated;
}