Astuces

La fonction WordPress add_query_arg()

WordPress est constitué d’une multitude de fonctions dites « Helpers » qui ont pour vocation de faciliter la vie des développeurs. Comme un bon développeur est un développeur fainéant, je vais vous présenter les bienfaits de la fonction add_query_arg().

A quoi sert add_query_arg() ?

La fonction add_query_arg() est un helper permettant de faciliter l’ajout d’arguments dans une URL. Le but premier étant de pouvoir construire dynamiquement et simplement des URLs complexes.

Comment add_query_arg() fonctionne ?

La fonction add_query_arg() accepte 3 paramètres :

namemixedle nom de l'argument
valuemixedla valeur de l'argument du premier paramètre
urlstringl’url sur laquelle ces arguments doivent s'appliquer. Par défaut, l'URL courante

add_query_arg() : l’exemple par le code

Cas facile

Créons un lien capable de re-diriger comme suit : http://monsite.com/?foo=bar

Vous auriez peut-être fait de la sorte, sans variables :

<?php echo home_url( '?foo=bar' );

Et avec une variable :

<?php echo 'https://monsite.com?foo=' . $baz;

Et maintenant l’exemple ci-dessous avec le add_query_arg() qui va nous permettre d’atteindre le même résultat :

<?php echo add_query_arg( 'foo', 'bar', home_url() );

En réalité ça devient cool, utile et « rentable » lorsque l’on a 2+ arguments dans l’URL. Surtout que l’on peut jouer avec une URL comprenant déjà des arguments, rien n’est « écrasé ». Il faut aussi prendre en considération que le slash final va être également automatiquement généré, si nécessaire.

Pas besoin d’être ingénieur pour comprendre que l’on se casse la tête pour rien ?!

Cas plus compliqué

Encore un peu perplexe ? Il est utile d’utiliser ce helper, mais dans quels cas ? Prenons un exemple un peu plus compliqué mais surtout concret, permettant d’afficher un bouton afin de calculer un itinéraire GMAP :

https://www.google.com/maps?q={mon_addresse}&key={gmap_api_key}

Ce qu’il faut savoir c’est que le comportement de add_query_arg() change selon les arguments que lui sont passés. Si le premier argument est un tableau, ce helper comprendra seul que les associations des clés/valeurs seront à utiliser dans la construction de l’URL et que l’argument 2 sera l’URL.

<?php $query_vars = array(
	'q'   => urlencode( 130 Avenue Jean-Jaurès, 75001, Paris ),
	'key' => 'oaOIpozPIEpizp11jKZAk',
);
echo add_query_arg( $query_vars, 'https://www.google.com/maps' );

Lorsque nous sommes sur 2+ arguments, cet helper va gérer seul l’ajout du ? pour le premier argument mais également les &amp; pour les n suivants.

Cas complexe

Passons maintenant à un cas beaucoup plus complexe, qui va nécessiter l’utilisation de tableaux multidimensionnels, qui, passés en argument de add_query_arg(), va associer les clés de chaque tableau constituant ainsi les « groupements » des arguments construit par l’association des clés/valeurs.

WHAT ?! A n’y rien comprendre, alors voici une représentation qui vaudra 1000 explications :

<?php add_query_arg( [ 'foo' => [ 'bar' => 'baz' ] ], 'https://monsite.com' );
/* https://monsite.com/?foo[bar]=baz */

Prenons donc maintenant un exemple à la hauteur de notre ambition et qui sera ni plus ni moins que la page des missions update du site arianespace.com : http://www.arianespace.com/mission-updates/?taxonomy[payload]=bsat-4a&taxonomy[client]=intelsat&taxonomy[mission]=none&taxonomy[post_tag]=none&date[year]=2017&date[month]=09&taxonomy[mission-update-category]=ariane-5

Avant donc de passer à la construction de notre tableau des arguments, analysons ensemble cette URL. On remarque qu’elle est découpée en « groupe » avec taxonomy d’un côté et date de l’autre. Donc nos deux tableaux de « niveau 0 ».

Que pour le « groupement » taxonomy, on y retrouve payload, client, mission, post_tag, mission-update-category et que date est constitué uniquement de year et month, qui seront respectivement au « niveau 1 ».

On construit ainsi le tableau des query_vars :

<?php $query_vars = [
	'taxonomy' => [ 
		'payload'  				  => 'bsat-4a',
		'client'   				  => 'intelsat',
		'mission'  				  => 'none',
		'post_tag' 				  => 'none',
		'mission-update-category' => 'ariane-5', 
	],
	'date' => [ 
		'year'  => 2017,
		'month' => 09, 
	],
];

Le plus dur est derrière nous ! Utilisons le :

<?php add_query_arg( $query_vars, get_post_type_archive_link( 'mission-update' ) );

Conclusions sur le add_query_arg

Il devient donc très utile d’utiliser ce helper, et ainsi économiser du temps pour la construction d’URL :

  • devient rentable lorsque l’on à ajouter 2 arguments ou plus dans l’URL
  • gestion des séparateurs : `?` pour le premier argument et `&` pour les n suivants
  • « n’écrase » pas les arguments déjà présents dans l’URL
  • gère automatiquement le slash final
  • l’URL est encodée avec urlencode_deep()
  • l’URL n’est pas escape, il faut donc la wrapper dans esc_url()
La fonction add_query_arg() signe la fin de la concaténation des bouts d’URL

 


Pour finir, laissez-moi dans les commentaires des suggestions d’utilisations pour lesquels vous vous seriez dit : « Cette fonction vient de me faire gagner du temps ! ».
Mais également si c’est la première fois que vous en entendez parler, dites-moi s’il a été facile pour vous de l’utiliser.

WordPressement vôtre