add_query_arg côté serveur : construire une URL sans concaténer de chaînes

Comment ajouter un paramètre page à une URL qui contient parfois déjà un ?filtre=actif, parfois rien du tout, sans écrire une série de conditions sur la présence du point d’interrogation ? C’est exactement le problème que add_query_arg() résout, et pourtant beaucoup de développeurs continuent à concaténer des chaînes à la main pour ce genre de lien.

Le résultat d’une concaténation manuelle finit tôt ou tard par produire une URL du type ?filtre=actif?page=2 ou &page=2 en tête de chaîne, deux erreurs qui passent souvent inaperçues en développement local mais qui cassent des liens en production.

Ce que fait add_query_arg()

add_query_arg() accepte soit un couple clé/valeur, soit un tableau associatif de plusieurs paramètres, et une URL de base optionnelle. Sans troisième argument, elle utilise l’URL de la requête courante telle que fournie par le serveur. Elle analyse la chaîne existante, ajoute ou remplace les paramètres demandés, et reconstruit une URL propre avec un seul point d’interrogation et des & correctement placés entre les paramètres.

Construire un lien de pagination

Un cas d’usage typique : une liste d’articles filtrée par catégorie, avec une pagination qui doit conserver le filtre actif d’une page à l’autre.

$page_suivante = add_query_arg(
    array( 'paged' => $numero_page + 1 ),
    get_pagenum_link()
);

echo '<a href="' . esc_url( $page_suivante ) . '">Page suivante</a>';

Le tableau permet d’ajouter plusieurs paramètres à la fois, par exemple pour combiner une pagination et un tri :

$lien_tri = add_query_arg(
    array(
        'orderby' => 'date',
        'order'   => 'desc',
    )
);

Un point souvent ignoré : la valeur false

Passer false comme valeur à une clé retire ce paramètre de l’URL au lieu de l’y ajouter avec la valeur littérale « false ». C’est utile pour construire un lien qui bascule un filtre : actif si le paramètre est présent, retiré sinon.

• Une clé absente de l’URL de départ est simplement ajoutée à la fin.
• Une clé déjà présente voit sa valeur remplacée, à la bonne position.
• Une valeur false supprime le paramètre correspondant de l’URL retournée.

Séparer construction et échappement

Un détail qui échappe souvent aux débutants : add_query_arg() ne fait aucun échappement HTML de l’URL retournée. Elle construit une URL techniquement correcte, mais destinée à être encore traitée avant affichage. La documentation officielle sur developer.wordpress.org le précise explicitement dans les notes de sécurité de la fonction : chaque sortie doit passer par esc_url() juste avant l’impression, jamais avant.

Pourquoi cette séparation a du sens

Faire deux passes distinctes — construction logique de l’URL, puis échappement au moment de l’affichage — évite le double encodage. Si l’échappement était intégré dans la fonction de construction, chaque manipulation supplémentaire de l’URL (par exemple un second appel à add_query_arg() plus loin) risquerait de ré-encoder des caractères déjà encodés, produisant des séquences comme %2526 au lieu de %26.

Un repère fiable dans son propre code : jamais d’add_query_arg() sans un esc_url() qui l’enveloppe à l’endroit exact où le lien est imprimé, pas avant.

Variante avec remove_query_arg

Pour l’opération inverse — retirer un paramètre sans connaître sa valeur — la fonction complémentaire est remove_query_arg(), qui accepte une clé ou un tableau de clés à supprimer d’une URL donnée. Les deux fonctions partagent la même logique d’analyse d’URL et se combinent naturellement dans un même bloc de construction de liens.

En résumé

Construire une URL de filtre ou de pagination à la main revient à réimplémenter, moins bien, ce que add_query_arg() fait déjà correctement depuis les débuts de WordPress. La fonction gère la présence ou l’absence du point d’interrogation, l’ordre des paramètres et les cas particuliers comme la suppression via false. Le seul point de vigilance reste l’échappement, à appliquer séparément et toujours au plus près de l’affichage.