Description

Relie un objet (poste, lien, etc) à un terme et sa taxonomie. Créer la relation entre ces deux derniers si elle n'existe pas déjà. Créer un terme s'il n'existe pas (en utilisant le slug).

Une relation signifie qu'un terme appartient à une taxonomie. Un terme n'a aucune utilité jusqu'à ce qu'on lui donne un contexte en définissant sous quelle taxonomie il existe.

Cette fonction ne vérifie pas s'il y a une relation entre le type de l'objet et la taxonomie. À cause de ça, les termes existants seront attachés par paire objet - terme si il y a ou pas une connexion entre l'objet et la taxonomie de ces termes-ci.

Peut-être que la fonction wp_set_post_terms() est plus utile depuis qu'elle vérifie les valeurs en convertissant les taxonomies séparées par des virgules et en validant les termes hiérarchiques en entiers.

Cela peut être confus mais le tableau d'ids retourné par la fonction wp_set_object_terms() proviennent des champs 'term_taxonomy_id' au lieu de 'term_id' de la base de donnée.

Paramètres

$object_id

(int) (Requis) Id de l'objet à associé à un terme.

$terms

(string | int | array) (Requis) Un simple slug, id ou un tableau de slugs ou d'ids de termes. Remplacera toutes les relations existantes avec la taxonomie donnée. En passant une valeur vide, la fonction supprimera toutes les relations des termes reliés à l'objet.

$taxonomy

(string) (Requis) Contexte dans lequel le terme est relié à l'objet.

$append

(bool) (Optionnel) Si réglé à false, la fonction supprimera la différence de termes.

Valeur par défaut : false

Retourne

(array | WP_Error)

  • Un tableau d'ids ('term_taxonomy_ids') des termes affectés à la taxonomie.
  • Un tableau vide si l'argument $terms vaut null ou '' - un message de succès si des termes ont été supprimé.
  • L'objet WP_Error si la taxonomie est invalide.
  • Une chaîne du premier terme appelé incorrectement dans $terms (les ids de termes invalides sont acceptés et insérés).

Structure de la fonction wp_set_object_terms()

Définie dans le fichier wp-includes/taxonomy.php à la ligne 2522 :

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 ( ! 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();
    $term_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;
        }

        $term_ids[] = $term_info['term_id'];
        $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 " . join( ',', $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_delete( 'last_changed', 'terms' );

    /**
     * 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 terms.
     * @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;
}

Fonctions et Hooks utilisés par wp_set_object_terms()

wp_cache_delete()

Supprime les contenus du cache correspondant à la clé et au groupe.

__()

Retourne la traduction d'un texte.

wp_update_term_count()

Met à jour la quantité de termes dans une taxonomie.

wp_get_object_terms()

Retourne les termes associés aux ids d'objets donnés, en fournissant les taxonomies correspondantes.

wp_insert_term()

Ajoute un nouveau terme à la base de donnée.

wp_remove_object_terms()

Supprime tous les termes associés à un objet donné.

add_term_relationship

Se lance juste avant qu'une relation objet - terme soit ajoutée.

added_term_relationship

Se lance juste après qu'une relation objet - terme soit ajoutée.

set_object_terms

Se lance après que les termes soient associés à un objet.

term_exists()

Détermine si le terme d'une taxonomie existe.

taxonomy_exists()

Détermine si un nom de taxonomie existe.

get_taxonomy()

Retourne l'objet d'une taxonomie en donnant son nom.

do_action()

Exécute des fonctions attachées à un hook spécifique.

is_wp_error()

Vérifie si la variable est une erreur WordPress.

Où trouver la fonction wp_set_object_terms() dans le CMS Wordpress

Exemples

Attacher des catégories au poste avec l'id 42 :
$cat_ids = array( 6, 8 );

// Si vous voulez être sûr que les ids soient des entiers :
$cat_ids = array_map( 'intval', $cat_ids );
$cat_ids = array_unique( $cat_ids );

$term_taxonomy_ids = wp_set_object_terms( 42, $cat_ids, 'category' );

if ( is_wp_error( $term_taxonomy_ids ) ) {
    // Code ici ...
}

Noter que toutes les catégories du poste seront supprimées sauf celles nouvellement ajoutées.
Faire attention quand on associe un terme déjà existant à un poste :
Le second paramètre $terms doit être un entier ou un tableau d'entier sinon WordPress créera un nouveau terme 
car il croira alors que c'est un slug de terme.

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

// Mauvais :
wp_set_object_terms( $post_id, $category_id, $taxonomy );

// Correcte :
wp_set_object_terms( $post_id, intval( $category_id ), $taxonomy );
Supprimer toutes les catégories d'un poste :
wp_set_object_terms( 42, null, 'category' );

// ou
wp_set_object_terms( 42, '', 'category' );

// ou
wp_set_object_terms( 42, array(), 'category' );
Ajouter des catégories à un poste en gardant celles qu'il a déjà :
$cat_ids = array( 6, 8 );

$term_taxonomy_ids = wp_set_object_terms( 42, $cat_ids, 'category', true );

if ( is_wp_error( $term_taxonomy_ids ) ) {
    // Code ici ...
}

Sources

Codex Wordpress : wp_set_object_terms()

Autres fonctions dans le même fichier : wp-includes/taxonomy.php

Retour