Fonction PHP add_rewrite_var() : Tout ce que vous devez savoir

add_rewrite_var() est une fonction de l'API WordPress (elle ne fait pas partie de la bibliothèque standard de PHP) qui enregistre une variable de requête personnalisée afin que WordPress la reconnaisse lors de l'analyse de l'URL. Par défaut, WordPress ne prend en compte qu'une liste fixe de variables de requête « publiques » (telles que p, page_id, cat, s). Toute variable absente de cette liste est silencieusement ignorée, même si elle apparaît dans l'URL. add_rewrite_var() ajoute votre variable à cette liste blanche pour que vous puissiez la lire ensuite avec get_query_var().

Cette page explique ce que fait la fonction, quand l'utiliser, sa syntaxe, un exemple complet et opérationnel, ainsi que les pièges courants qui font apparaître les variables de requête personnalisées comme « vides ».

Ce que fait la fonction add_rewrite_var()

Lorsqu'une requête arrive, WordPress la fait passer par ses règles de réécriture et produit un ensemble de variables de requête. Pour des raisons de sécurité, seules les variables connues sont conservées. add_rewrite_var() étend cet ensemble autorisé avec un nom de variable supplémentaire, après quoi :

• La variable peut être utilisée dans des règles de réécriture personnalisées créées avec add_rewrite_rule().
• Sa valeur devient lisible via get_query_var( 'name' ) dans la requête principale.

Sans enregistrement de la variable, get_query_var() retourne une chaîne vide quelle que soit la valeur présente dans l'URL.

Syntaxe

add_rewrite_var( string $name ): void

La fonction ne retourne rien (void) ; son seul effet est d'enregistrer le nom.

Quand l'utiliser

Utilisez add_rewrite_var() lorsque vous construisez des URL conviviales/SEO dont les segments doivent être lus comme des valeurs nommées — par exemple un filtre de liste (/shop/?filter=red) ou un endpoint personnalisé (/profile/123/). Si vous lisez uniquement les variables via la superglobale $_GET directement, vous n'avez pas besoin de cette fonction ; elle existe spécifiquement pour que les valeurs survivent au filtrage des variables de requête et au système de réécriture de WordPress.

Un exemple complet

WordPress construit sa requête tôt dans le cycle de traitement, la variable doit donc être enregistrée avant que cela ne se produise. L'emplacement standard est un callback accroché à l'action init :

function my_register_query_var() {
    // Whitelist a custom query variable named "filter".
    add_rewrite_var( 'filter' );
}
add_action( 'init', 'my_register_query_var' );

function my_read_query_var() {
    // Read the value WordPress parsed from the URL, e.g. /shop/?filter=red
    $filter = get_query_var( 'filter' );

    if ( ! empty( $filter ) ) {
        echo 'Filtering by: ' . esc_html( $filter );
    }
}
add_action( 'template_redirect', 'my_read_query_var' );

Ici, add_rewrite_var( 'filter' ) enregistre le nom, et get_query_var( 'filter' ) lit la valeur que WordPress a associée à ce nom pour la requête en cours. La vérification ! empty() protège contre l'affichage de quoi que ce soit lorsque la variable est absente ou vide.

Pièges courants

• Enregistrez tôt. Appelez la fonction sur init (ou avant). L'enregistrer après la construction de la requête principale n'a aucun effet pour la requête en cours.
• Videz les règles de réécriture. Si vous ajoutez aussi des règles de réécriture qui utilisent la variable, videz les règles une fois — visitez Réglages → Permaliens ou appelez flush_rewrite_rules() lors de l'activation du plugin. N'appelez pas flush_rewrite_rules() à chaque requête ; c'est coûteux.
• Valeur vide ? Une valeur vide retournée par get_query_var() signifie presque toujours que la variable n'a jamais été inscrite sur la liste blanche, ou qu'elle a été enregistrée trop tard.

Fonctions associées

• reset_rewrite_vars() — efface le tableau global des variables de réécriture, annulant ce qu'a enregistré add_rewrite_var(). Utile lorsque vous avez besoin que WordPress recalcule les variables de requête pour la requête en cours.

Conclusion

add_rewrite_var() ajoute un nom unique à la liste des variables de requête reconnues par WordPress afin qu'il survive à l'étape de réécriture/analyse et puisse être lu avec get_query_var(). Enregistrez-le sur le hook init, videz les permaliens si vous l'associez à des règles de réécriture personnalisées, et vous pourrez étendre proprement la gestion des URL de WordPress.

Pratique