Chapitre 5.3 — La Boucle (The Loop)

⏱️ TL;DR — La Boucle est le motif central du rendu WordPress : parcourir les résultats de la requête et afficher chaque contenu. Sa forme canonique — if ( have_posts() ) { while ( have_posts() ) { the_post(); … } } — configure à chaque tour le « post courant », ce qui rend disponibles les template tags (the_title(), the_content(), the_permalink()…). Comprendre la Boucle, c’est comprendre comment un thème transforme des données en HTML — et pourquoi le « contexte global » du post existe.

🎯 Objectifs

• Écrire et lire une Boucle standard.
• Comprendre le post courant et les template tags qui en dépendent.
• Distinguer Boucle de la main query vs Boucle d’une requête secondaire.
• Éviter les pièges (globals, wp_reset_postdata).

1. La forme canonique

if ( have_posts() ) :
    while ( have_posts() ) :
        the_post();  // ← configure le « post courant »
        ?>
        <article>
            <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
            <div class="content"><?php the_content(); ?></div>
        </article>
        <?php
    endwhile;
else :
    echo '<p>Aucun contenu.</p>';
endif;

• have_posts() : reste-t-il des résultats à afficher ?
• the_post() : avance au contenu suivant et le définit comme post courant (remplit la globale $post et le contexte).
• Les template tags (the_title(), the_content()…) affichent les données du post courant — d’où l’importance de the_post().

💡 Pour un dev React — La Boucle est un .map() impératif sur une liste, avec un twist : au lieu de passer chaque élément en argument (posts.map(post => …)), WordPress met le post courant dans un contexte global que les template tags lisent implicitement. the_post() = « rends l’élément courant disponible dans le contexte » ; the_title() = « lis le titre depuis le contexte ». C’est un style plus ancien (état global) que vos props explicites, mais l’intention — pour chaque contenu, rends ce template — est identique.

2. Les template tags (préfixes the_ vs get_the_)

Une convention essentielle :

the_title();                 // affiche
$titre = get_the_title();    // récupère pour le traiter
echo esc_html( strtoupper( get_the_title() ) );

⚠️ Piège — Beaucoup de tags existent en deux versions (the_permalink() / get_permalink(), the_ID() / get_the_ID()). Utiliser the_ là où l’on voulait récupérer (et non afficher) produit un affichage parasite. Règle : the_ pour afficher, get_the_ pour obtenir.

3. Boucle principale vs requête secondaire

• Boucle de la main query (ci-dessus) : affiche le contenu de la page (déterminé par l’URL, ch. 5.1). Pas besoin de créer la requête ; on la parcourt.
• Boucle d’une requête secondaire : quand vous voulez afficher autre chose (ex. « 3 articles liés »), vous créez un WP_Query (ch. 5.5) et bouclez dessus :

$related = new WP_Query( array( 'posts_per_page' => 3, 'category_name' => 'actus' ) );
if ( $related->have_posts() ) {
    while ( $related->have_posts() ) {
        $related->the_post();
        the_title( '<h3>', '</h3>' );
    }
    wp_reset_postdata(); // ⚠️ restaure le post courant de la main query
}

⚠️ Piège n°1 — oublier wp_reset_postdata(). Après avoir bouclé sur une requête secondaire, il faut restaurer le post courant de la main query avec wp_reset_postdata(). Sinon, le reste du template (commentaires, navigation, tags) croit être sur le dernier post de votre requête secondaire → bugs subtils.

4. Les globales autour de la Boucle

La Boucle s’appuie sur des variables globales : $post (le post courant), $wp_query (la requête principale), $wp_the_query. Les template tags les lisent en coulisses. On les manipule rarement à la main, mais savoir qu’elles existent explique des comportements (et pourquoi wp_reset_postdata() est nécessaire).

💡 Pour un dev React — Cet état global mutable ($post) est l’opposé de votre habitude des props immuables. C’est un héritage historique de WordPress. Les approches modernes (blocs dynamiques, REST, headless) s’en éloignent : en headless (Partie 9), vous recevez des données explicites (JSON) et bouclez côté React de façon familière, sans globales.

5. La Boucle dans les thèmes classiques vs blocs

• Thème classique : vous écrivez la Boucle en PHP dans les fichiers de template (index.php, single.php…), Partie 6.
• Thème bloc (FSE) : la Boucle est produite par le bloc Requête (Query Loop, ch. 3.3) — vous n’écrivez plus le PHP, vous composez des blocs. Le concept sous-jacent (parcourir des résultats, afficher chaque post) est identique.

✏️ Exercices

1. Écrivez une Boucle minimale qui affiche le titre (lien) et l’extrait de chaque contenu.
2. Après une boucle sur new WP_Query(...), quelle fonction devez-vous appeler et pourquoi ?
3. Quelle est la différence entre the_title() et get_the_title() ?

if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
    <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
    <?php the_excerpt();
endwhile; endif;

🧠 Quiz de révision

Chapitre suivant : La hiérarchie de gabarits.