Sur le papier, ajouter une règle de réécriture pour transformer /produit/123/ en /boutique-outillage/ref-123-perceuse/ ressemble à une opération simple : on appelle add_rewrite_rule(), on vide le cache de permaliens, et le tour est joué. En pratique, une règle mal bornée intercepte aussi des URL que WooCommerce utilise pour la pagination du catalogue, comme /boutique/page/2/, et provoque des pages blanches ou des 404 aléatoires selon la position de la nouvelle règle dans la pile.
Ce tutoriel détaille, étape par étape, comment ajouter une règle de réécriture pour une URL de fiche produit personnalisée sans entrer en collision avec les règles natives de pagination du catalogue WooCommerce.
Étape 1 : comprendre où s’insère votre règle
WordPress évalue les règles de réécriture dans l’ordre où elles apparaissent dans le tableau global des règles, du plus spécifique au plus générique. Les règles ajoutées par une extension via add_rewrite_rule() sont, par défaut, injectées avant les règles du cœur si vous utilisez le paramètre 'top', ou après si vous utilisez 'bottom'. Une règle de fiche produit doit être positionnée en top pour être testée avant les règles génériques de pagination, sans quoi WordPress essaiera d’abord de faire correspondre l’URL à un motif de pagination existant.
Étape 2 : écrire une règle bornée
add_action( 'init', function () {
add_rewrite_rule(
'^boutique-outillage/ref-([0-9]+)-([a-z0-9-]+)/?$',
'index.php?post_type=product&p;=$matches[1]',
'top'
);
} );Le motif capture explicitement un identifiant numérique suivi d’un slug, ce qui exclut naturellement les segments page/2 générés par la pagination. C’est la spécificité du motif, pas sa position seule, qui garantit l’absence de collision : un motif trop permissif comme ^boutique-outillage/(.+)$ capturerait aussi bien page/2 que l’identifiant produit, et casserait la navigation.
Étape 3 : vider le cache de permaliens au bon moment
Une règle de réécriture ajoutée par du code n’est effective qu’après un appel à flush_rewrite_rules(), qui régénère la table stockée en option. Cet appel est coûteux : il ne doit jamais être exécuté à chaque chargement de page, uniquement à l’activation de l’extension ou après une modification de configuration explicite de l’administrateur.
- Enregistrer la règle sur le hook
init, à chaque requête - Appeler
flush_rewrite_rules()uniquement sur le hook d’activation de l’extension - Proposer un bouton d’administration pour forcer un nouveau flush si la structure de permaliens change
Étape 4 : vérifier la résolution avec wp_parse_request
Pour confirmer que votre règle capture bien l’identifiant attendu sans intercepter la pagination, il est utile d’inspecter les query vars résolues pour une URL donnée. Le filtre request, déclenché après le parsing, permet un contrôle rapide en développement :
add_filter( 'request', function ( $query_vars ) {
if ( isset( $query_vars['p'] ) ) {
error_log( print_r( $query_vars, true ) );
}
return $query_vars;
} );Tester ensuite /boutique-outillage/ref-123-perceuse/ puis /boutique/page/2/ doit produire deux jeux de query vars distincts, le second conservant bien paged et non un p incorrect.
Ce qu’il ne faut jamais faire
Éviter absolument de redéfinir la structure de permaliens globale de la boutique (woocommerce_permalinks) pour résoudre un cas particulier de fiche produit : cette option affecte l’ensemble du catalogue, y compris les archives de catégories et leur pagination, et un changement mal maîtrisé nécessite ensuite de régénérer tous les liens internes existants.
Documenter la règle pour la prochaine personne qui y touchera
Une règle de réécriture personnalisée, une fois en production, devient vite invisible dans le code : elle ne se déclenche que sur un motif d’URL précis, et personne ne pense à la revérifier lors d’une mise à jour de structure de permaliens. Un simple commentaire au-dessus de l’appel à add_rewrite_rule(), précisant l’intention et le motif exclu volontairement, fait gagner un temps précieux au développeur qui devra un jour la modifier sans disposer du contexte d’origine.
En résumé
La collision entre une règle personnalisée et la pagination native n’est jamais une fatalité : elle vient presque toujours d’un motif de capture trop large. Borner précisément l’expression régulière, positionner la règle en top, et vérifier les query vars réellement résolues suffisent à cohabiter proprement avec le système de pagination du catalogue.
