Chapitre 5.9 — Rewrite API : les URLs propres

⏱️ TL;DR — La Rewrite API est ce qui transforme des URLs « jolies » (/livres/dune/) en paramètres de requête internes que WordPress résout. Elle repose sur des règles de réécriture (rewrite rules) et des query vars. Le plus souvent, vous n’y touchez pas directement : déclarer un Custom Post Type ou une taxonomie (Partie 7) génère automatiquement les bonnes URLs. Vous n’ouvrez le capot que pour des endpoints custom (ex. /mon-compte/commandes/) ou des structures d’URL sur mesure — et alors la règle d’or est de régénérer les règles (flush_rewrite_rules) au bon moment (à l’activation, jamais à chaque requête).

🎯 Objectifs

• Comprendre le rôle des rewrite rules et des query vars.
• Savoir que CPT/taxonomies génèrent leurs URLs automatiquement.
• Ajouter un endpoint ou une règle custom quand c’est nécessaire.
• Maîtriser flush_rewrite_rules() (quand, et surtout quand pas).

1. Le rôle : de l’URL propre à la requête

Sans réécriture, WordPress répondrait à des URLs du type ?post_type=livre&name=dune. La réécriture permet /livres/dune/ : plus lisible, meilleure pour le SEO et le partage (ch. 2.1).

• Les rewrite rules sont un ensemble de regex associées à des jeux de query vars. WordPress les teste contre l’URL demandée.
• Les query vars sont les variables reconnues (post_type, name, p, category_name, + les vôtres).
• Sur Apache, un .htaccess redirige tout vers index.php ; sur Nginx, une directive équivalente. Ensuite, WordPress fait le vrai routage en interne (pas le serveur web).

2. Le cas courant : rien à faire (ou presque)

La plupart du temps, vous n’écrivez aucune règle. Déclarer un CPT ou une taxonomie avec l’option rewrite (Partie 7) génère automatiquement les URLs :

register_post_type( 'livre', array(
    'public'  => true,
    'rewrite' => array( 'slug' => 'livres' ), // → /livres/{slug}/
    // …
) );

→ WordPress crée les rewrite rules pour /livres/… pour vous. Idem pour les archives (/livres/) et les taxonomies custom. Ne réinventez pas ce que l’enregistrement fournit.

⚠️ Piège n°1 — le CPT en 404 après création. Vous déclarez un CPT livre, mais /livres/dune/ renvoie 404. Cause : les rewrite rules n’ont pas été régénérées. Solution : aller dans Réglages → Permaliens → Enregistrer (régénère), ou appeler flush_rewrite_rules() à l’activation du plugin (§4). C’est le piège classique des CPT.

3. Ajouter une query var et une règle custom

Pour une URL vraiment sur mesure (ex. /archive/2026/07/ gérée autrement, ou /api-maison/xyz/), on ajoute une query var et une règle :

add_action( 'init', 'monplugin_rewrite' );
function monplugin_rewrite() {
    add_rewrite_tag( '%livre_action%', '([^&]+)' );      // reconnaît la var
    add_rewrite_rule(
        '^livres/([^/]+)/telecharger/?$',                // regex de l'URL
        'index.php?post_type=livre&name=$matches[1]&livre_action=telecharger',
        'top'                                            // priorité sur les règles existantes
    );
}
 
// Rendre la query var accessible
add_filter( 'query_vars', function ( $vars ) {
    $vars[] = 'livre_action';
    return $vars;
} );
 
// L'exploiter (ex. avant le rendu)
add_action( 'template_redirect', function () {
    if ( 'telecharger' === get_query_var( 'livre_action' ) ) {
        // servir un fichier, incrémenter un compteur, etc.
    }
} );

Pour des endpoints attachés à un type (ex. /mon-compte/commandes/), il existe aussi add_rewrite_endpoint() (utilisé par WooCommerce pour les sous-pages du compte, Partie 10).

4. flush_rewrite_rules() : au bon moment uniquement

Régénérer les règles est coûteux (réécriture des règles, parfois du .htaccess). Règle d’or :

• ✅ À l’activation du plugin (register_activation_hook), après avoir enregistré le CPT/les règles.
• ✅ Manuellement en dev : Réglages → Permaliens → Enregistrer.
• ❌ Jamais à chaque requête (ex. sur init) : cela détruit la performance du site.

register_activation_hook( __FILE__, function () {
    monplugin_enregistrer_cpt(); // enregistre le CPT (mêmes règles qu'au runtime)
    flush_rewrite_rules();       // régénère UNE fois, à l'activation
} );
register_deactivation_hook( __FILE__, 'flush_rewrite_rules' ); // nettoyage

⚠️ Piège n°2 — flush_rewrite_rules() sur init. Le tutoriel mal fichu vous fait appeler flush_rewrite_rules() à chaque chargement (dans la fonction d’init). Résultat : les règles sont recalculées à chaque page → site lent. On flush une seule fois, à l’activation.

💡 Pour un dev React — La Rewrite API est le routeur de WordPress : des regex → paramètres (comme des routes dynamiques /livres/[slug]), sauf que la table de routes est générée et mise en cache (d’où le besoin de la « régénérer » quand elle change — l’équivalent d’un rebuild du manifeste de routes). En pratique : laissez les CPT/taxonomies générer les routes, ne codez des règles que pour les cas spéciaux, et flush uniquement à l’activation.

5. Débogage

• Après tout ajout de CPT/règle : enregistrer les permaliens (ou flush à l’activation).
• Le plugin « Rewrite Rules Inspector » (ou Query Monitor) liste les règles actives et celle qui a matché l’URL courante.
• Vérifier l’ordre ('top' place la règle avant les règles par défaut) et la regex.

✏️ Exercices

1. Vous créez un CPT evenement et /evenements/gala/ renvoie 404. Quelle est la cause et la correction ?
2. Pourquoi ne faut-il jamais appeler flush_rewrite_rules() sur le hook init en production ?
3. Où et comment appelle-t-on flush_rewrite_rules() correctement pour un plugin qui déclare un CPT ?

🧠 Quiz de révision

Partie suivante : Partie 6 — Développer des thèmes.