# Générer une URL de fiche produit personnalisée sans casser la pagination du catalogue

> Ajouter une règle de réécriture pour des permaliens produit sur mesure peut silencieusement casser la pagination native du catalogue WooCommerce. Voici la marche à suivre correcte.

- Auteur : WordPress Développement
- Publié le : 2020-11-02
- Mis à jour le : 2020-11-02
- Catégorie : E-commerce
- URL : https://www.wpmoderne.fr/ecommerce/generer-url-fiche-produit-rewrite-api-sans-casser-pagination/

## L’essentiel

- add_rewrite_rule doit être combinée à flush_rewrite_rules au bon moment
- Une règle trop générique intercepte les URL de pagination du catalogue
- wp_parse_request permet de vérifier les query vars réellement résolues

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

> L'essentiel à retenir : add_rewrite_rule doit être combinée à flush_rewrite_rules au bon moment ; Une règle trop générique intercepte les URL de pagination du catalogue ; wp_parse_request permet de vérifier les query vars réellement résolues

```
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.

1. Enregistrer la règle sur le hook `init`, à chaque requête
2. Appeler `flush_rewrite_rules()` uniquement sur le hook d'activation de l'extension
3. 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.