Faire des appels HTTP avec WordPress grâce à wp_remote_*()

Communiquer avec des systèmes externes est souvent nécessaire lors du développement d’une extension back-end WordPress sur-mesure.

En PHP, on dispose d’APIs comme cURL, de fonctions comme file_get_contents ou de librairies comme Guzzle.

Mais WordPress dispose d’un panel de fonctions permettant de faciliter les interactions avec des URLs/APIs et exécuter des requêtes HTTP de manière standardisée et optimisée. Découvrons ça !

Développer avec l’API HTTP de WordPress

Quelques exemples courants d’appels HTTP dans WordPress

Votre site WordPress contacte les serveurs de WordPress.org régulièrement pour vérifier l’existence de nouvelles versions des plugins, thèmes et du cœur WordPress lui-même.

Ou si vous développez votre propre extension ou thème WordPress, vous aurez peut être besoin d’appeler des URLs externes pour :

• ajouter des abonnés à une liste Mailchimp,
• envoyer des e-mails via SendInBlue ou Amazon SES,
• importer des données provenant d’APIs externes,
• écrire des données de formulaires dans un tableau Notion,
• téléverser des images vers des stockages tiers comme Amazon S3 ou Google Cloud Storage.

Les fonctions pour envoyer des requêtes HTTP

WordPress dispose de 4 fonctions wp_remote_*() qui permettent d’exécuter des requêtes HTTP vers des URLs. Elles sont les suivantes.

1. wp_remote_get( $url, $args ) pour faire une requête GET,
2. wp_remote_post( $url, $args ) pour faire une requête POST,
3. wp_remote_head( $url, $args ) pour faire une requête HEAD,
4. wp_remote_request( $url, $args ) pour faire une requête HTTP comme bon vous semble !

Ces fonctions acceptent comme arguments, dans l’ordre :

1. l’URL $url à appeler,
2. un tableau de paramètres $args pour configurer l’exécution de la requête.

Si vous ne voulez qu’en retenir qu’une, il s’agit donc bien de wp_remote_request() qui vous permettra d’exécuter n’importe quelle méthode (GET, POST, HEAD, PUT, DELETE, etc.) sur l’URL de votre choix.

Un point sur les paramètres existants

Le deuxième argument $args est un tableau permettant d’indiquer des paramètres pour exécuter la requête. En plus de la méthode, d’autres réglages intéressants sont disponibles. Détaillons les principaux dans le tableau ci-dessous :

Les fonctions pour analyser les réponses HTTP reçues

Après exécution de notre appel HTTP, nous allons vouloir analyser certaines parties de la réponse (headers, corps, statut HTTP, etc.). Des fonctions utilitaires vont nous permettre de simplifier cela :

• wp_remote_retrieve_headers( $response ) renvoie un tableau contenant les headers de la réponse,
• wp_remote_retrieve_header( $response, $name ) permet de récupérer un seul header de la réponse,
• wp_remote_retrieve_response_code( $response ) permet de récupérer le statut/code HTTP en format integer
• wp_remote_retrieve_response_message( $response ) permet de lire le message de la réponse,
• wp_remote_retrieve_body( $response ) permet de lire le corps de la réponse,
• wp_remote_retrieve_cookies( $response ) renvoie un tableau listant les cookies de la réponse,
• wp_remote_retrieve_cookie( $response, $name ) permet de lire la valeur d’un seul cookie dans la réponse.

Exemples pratiques

Lister les derniers Gists d’un utilisateur GitHub

Le code du plugin partagé sur GitHub présente un cas concret de l’utilisation de l’API HTTP de WordPress. Après avoir cloné le repo, vous pourrez activer l’extension puis utiliser le shortcode [gists user="username" amount="10"] pour afficher les 10 derniers Gists d’un utilisateur.

L’affichage du shortcode va appeler l’API publique de GitHub et stocker les résultats dans une option. Ce résultat est mis en cache dans la table d’options WordPress pendant 1 journée pour éviter les appels inutiles.

Utiliser wp_remote_request() pour interroger l’API GitHub

function get_user_gists_via_api( $username = '', $amount = 10 ) {
	$gists = [];

	$response = wp_remote_request(
		sprintf( 'https://api.github.com/users/%1$s/gists?per_page=%2$s', sanitize_text_field( $username ), absint( $amount ) ),
		[
			'timeout' => 15,
			'method'  => 'GET',
		]
	);

	if ( (int) wp_remote_retrieve_response_code( $response ) === 200 ) {
		$gists = json_decode( wp_remote_retrieve_body( $response ) );
	}

	return $gists;
}

Décortiquons la fonction en charge d’appeler l’API de GitHub :

1. wp_remote_request() est utilisé pour exécuter la requête HTTP en indiquant en paramètre un délai d’exécution de 15 secondes maximum et la méthode GET,
2. avec wp_remote_retrieve_response_code(), on s’assure que le statut HTTP de la réponse est bien 200 (succès),
3. on décode le JSON de la réponse que l’on récupère avec wp_remote_retrieve_body().

Exécuter la même requête GET avec cURL

Pour comparer, voici l’équivalent PHP en utilisant cURL :

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.github.com/users/psaikali/gists?per_page=50",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Avouons que l’API fournie par WordPress est nettement plus lisible et facile à comprendre, comparé au code cURL très verbeux et fastidieux à mettre en place.

Enregistrer une adresse mail dans une liste MailChimp

Dans le tutoriel ci-dessous, la fonction wp_remote_post() est utilisée pour inscrire un utilisateur dans une liste d’abonnés en utilisant l’API de MailChimp.

Aller plus loin

Enfin, voici quelques excellentes ressources complémentaires (en anglais) qui vous permettront d’aborder le sujet sous un autre angle :

• Why You Should Use the WordPress HTTP functions to Make API Requests par Delicious Brains
• A Look at the WordPress HTTP API par Tom McFarlin sur Tuts+
• Designing a class: WordPress API client par Carl Alexander
• A Guide to Async HTTP Requests for WordPress par Josh Pollock sur Torque