wp_set_object_terms( int $object_id, string|int|array $terms, string $taxonomy, bool $append = false )
Créer une relation entre un objet donné et un terme.
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
Sources
Codex Wordpress : wp_set_object_terms()
Autres fonctions dans le même fichier : wp-includes/taxonomy.php