wp_reset_postdata()

Définition : wp_reset_postdata() restaure les données globales de publication attendues par la requête principale après une boucle secondaire utilisant setup_postdata() ou WP_Query::the_post(). Elle évite des titres et liens incohérents.

Comprendre et utiliser

À quoi sert ce terme ?

Cette restauration maintient les balises de modèle dans le bon contexte après l’affichage de contenus complémentaires. Sans elle, le bas d’une page peut réutiliser par erreur les données du dernier élément secondaire.

Fonctionnement technique

La fonction exploite la requête principale globale et rétablit notamment les données liées à $post. Elle ne remet pas à zéro tous les paramètres de requête et n’est pas interchangeable avec wp_reset_query().

Dans quels contextes l’utiliser ?

À appeler à la fin d’une boucle WP_Query personnalisée qui a utilisé the_post(). Pour une simple boucle foreach d’objets sans modification du contexte global, elle peut ne pas être nécessaire.

Cas concret : ATOOLPHA

ATOOLPHA montre trois articles connexes dans la page d’une fiche, puis doit revenir au titre de la fiche principale.

Exemple de code commenté

Extrait PHP destiné à un plugin ou à un template WordPress, dans le contexte indiqué ; pas au contenu HTML de l’article.

<?php
$related = new WP_Query( array(
    'post_type' => 'post', 'posts_per_page' => 3,
) );
if ( $related->have_posts() ) {
    while ( $related->have_posts() ) {
        $related->the_post();
        echo '<p>' . esc_html( get_the_title() ) . '</p>';
    }
}
wp_reset_postdata(); // Restaurer la publication principale.

Décryptage de l’exemple

Chaque appel the_post() place temporairement l’article secondaire dans les données globales utilisées par les balises. wp_reset_postdata() rétablit le contexte nécessaire aux instructions du modèle qui suivent.

Résultat attendu

Les trois titres associés apparaissent ; après la restauration, les balises appelées dans le template reprennent le contenu principal.

Exercice pratique et vérification

Afficher avant la boucle un titre principal, puis la liste secondaire et de nouveau le titre principal. Vérifier que la valeur avant/après est identique.

Précautions et limites

Ne pas employer wp_reset_query() pour compenser une mauvaise architecture de requête. Éviter query_posts(), qui modifie la requête principale et rend les effets plus difficiles à maîtriser.

À ne pas confondre

wp_reset_postdata() restaure $post ; wp_reset_query() remet en jeu un objet de requête global modifié, ce qui répond à une autre situation.

Diagnostic avancé

Si le titre du pied de page ou du bloc suivant change après une liste secondaire, rechercher une boucle sans restauration ou un setup_postdata() non équilibré.

Choix d’architecture et déploiement

Un composant secondaire doit préserver les variables globales consommées par le reste du thème. Documenter le cycle complet ouverture, itération et restauration. Dans une application à composants autonomes, préférer parfois des méthodes qui n’altèrent pas le contexte global.