get_the_terms mal utilisé : le piège des taxonomies hiérarchiques en B2B

Symptôme. Sur un catalogue de pièces industrielles organisé en familles et sous-familles via une taxonomie hiérarchique famille_produit, le fil d’ariane affiché sur une fiche produit saute parfois la catégorie parente pour n’afficher que la sous-catégorie, alors que le produit est pourtant correctement classé dans les deux niveaux depuis l’écran d’administration.

Le code incriminé ressemble presque toujours à ceci :

$termes = get_the_terms( get_the_ID(), 'famille_produit' );
$terme  = $termes[0];
echo esc_html( $terme->name );

Diagnostic

get_the_terms() retourne un tableau contenant tous les termes assignés au post pour la taxonomie donnée, y compris les termes parents et enfants, sans garantie sur leur ordre. Prendre systématiquement $termes[0] revient à parier que le premier élément du tableau est le terme le plus spécifique, ce qui n’est vrai ni par documentation ni par convention : l’ordre dépend de l’ordre d’insertion en base de données, qui peut varier selon la façon dont les termes ont été assignés au fil du temps.

Sur un produit classé à la fois dans Roulements (parent) et Roulements à billes (enfant), le tableau peut tout aussi bien retourner le parent en premier que l’enfant, selon l’historique d’édition de la fiche. C’est cette instabilité qui explique pourquoi le bug n’apparaît pas sur tous les produits, ni de façon reproductible en environnement de développement où les données ont été insérées dans un ordre différent.

Reconstruire la hiérarchie proprement

Le correctif consiste à ne jamais se fier à l’ordre du tableau, mais à identifier explicitement le terme le plus profond dans la hiérarchie, celui dont aucun autre terme assigné n’est un enfant :

function wpm_terme_le_plus_specifique( $post_id, $taxonomie ) {
    $termes = get_the_terms( $post_id, $taxonomie );

    if ( empty( $termes ) || is_wp_error( $termes ) ) {
        return null;
    }

    $ids_termes = wp_list_pluck( $termes, 'term_id' );

    foreach ( $termes as $terme ) {
        $a_un_enfant_present = false;

        foreach ( $termes as $autre ) {
            if ( $autre->parent === $terme->term_id ) {
                $a_un_enfant_present = true;
                break;
            }
        }

        if ( ! $a_un_enfant_present ) {
            return $terme;
        }
    }

    return $termes[0];
}

Construire le fil d’ariane complet

Une fois le terme le plus spécifique identifié, la fonction native get_ancestors() permet de remonter toute la hiérarchie parente pour afficher un fil d’ariane complet, du plus général au plus spécifique :

$terme_specifique = wpm_terme_le_plus_specifique( get_the_ID(), 'famille_produit' );

if ( $terme_specifique ) {
    $ancetres = array_reverse( get_ancestors( $terme_specifique->term_id, 'famille_produit' ) );
    $ancetres[] = $terme_specifique->term_id;

    $fil_ariane = array();
    foreach ( $ancetres as $id_terme ) {
        $t = get_term( $id_terme, 'famille_produit' );
        $fil_ariane[] = $t->name;
    }

    echo esc_html( implode( ' > ', $fil_ariane ) );
}

Correctif

Le correctif tient en un principe simple à retenir : ne jamais indexer directement le tableau retourné par get_the_terms() pour en déduire une hiérarchie. Toute logique dépendant du niveau hiérarchique d’un terme doit passer par get_ancestors(), $term->parent, ou une fonction qui compare explicitement les parentés entre les termes assignés, comme illustré ci-dessus.

Prévention

• Documenter dans le code toute utilisation de get_the_terms() qui suppose un ordre particulier, pour qu’un futur relecteur repère immédiatement le risque.
• Ajouter un test manuel systématique sur un produit classé dans au moins deux niveaux de la hiérarchie avant de valider un affichage basé sur les taxonomies.
• Préférer wp_get_post_terms() avec l’argument orderby réglé sur term_order uniquement si un tri manuel a été explicitement configuré dans l’administration, sinon le même piège persiste.

Conseil maison : chaque fois qu’une fonction retourne un tableau de termes, posez-vous la question « cet ordre est-il garanti par la documentation ou seulement observé par hasard sur mon jeu de données actuel ? ». La réponse évite ce genre de bug difficile à reproduire.

En résumé

Ce bug ne provient jamais d’un dysfonctionnement de get_the_terms(), mais d’une hypothèse implicite sur l’ordre de son résultat. Sur un catalogue industriel à taxonomies profondes, reconstruire explicitement la hiérarchie via les relations parent-enfant reste le seul moyen fiable d’afficher un fil d’ariane cohérent, quel que soit l’historique de classement des produits.