GuzzleHTTP/Promises pour PHP : guide complet avec exemples

Bienvenue dans ce guide détaillé sur la bibliothèque GuzzleHTTP/Promises pour le langage PHP. Cette bibliothèque est l’un des piliers de l’écosystème Guzzle et offre une implémentation puissante du modèle « Promise » pour la programmation asynchrone. Que vous travailliez avec des requêtes HTTP, des tâches parallèles ou que vous souhaitiez simplement rendre votre code PHP plus efficace et lisible, cet article est fait pour vous.

1. Qu’est-ce que c’est et pourquoi l’utiliser ?

GuzzleHTTP/Promises est une bibliothèque PHP qui implémente le concept de promesses (Promises) et d’exécution asynchrone de tâches. Elle fait partie de l’écosystème Guzzle, mais peut être utilisée de manière totalement indépendante du client HTTP. L’idée principale des promesses est de créer un objet représentant le résultat d’une opération asynchrone, qui peut être obtenu maintenant, plus tard ou jamais. Cela permet d’écrire du code qui ne bloque pas l’exécution du programme en attendant la fin d’opérations longues.

Pourquoi en avoir besoin en PHP ? Traditionnellement, PHP est un langage synchrone où chaque opération s’exécute séquentiellement. Cependant, avec la montée en puissance des microservices, des intégrations API et du travail avec des services externes, le besoin de gérer efficacement les tâches parallèles s’est imposé. GuzzleHTTP/Promises résout ce problème en permettant de lancer plusieurs opérations simultanément (par exemple, plusieurs requêtes HTTP vers différentes API) et de traiter leurs résultats au fur et à mesure, sans attendre l’exécution de chacune l’une après l’autre.

La bibliothèque fournit un ensemble complet d’outils pour travailler avec du code asynchrone : création de promesses, combinaison, chaînage d’appels, gestion des erreurs et contrôle des délais d’attente. Elle est devenue le standard de facto pour le travail asynchrone dans la communauté PHP et est utilisée dans des projets populaires comme Laravel, Symfony, WordPress (via des plugins) et, bien sûr, le client HTTP Guzzle lui-même.

2. Installation

L’installation de la bibliothèque se fait via Composer, le gestionnaire de paquets standard pour PHP. Exécutez la commande suivante dans le terminal à la racine de votre projet :

composer require guzzlehttp/promises

Si vous utilisez le client HTTP Guzzle, la bibliothèque de promesses est déjà incluse dans ses dépendances et aucune installation séparée n’est nécessaire. Après l’installation, assurez-vous que le fichier vendor/autoload.php est inclus dans votre script :

require 'vendor/autoload.php';

3. Démarrage rapide — exemple minimal fonctionnel

Créons un exemple simple pour travailler avec les promesses. Nous allons créer une promesse qui se « résout » après 1 seconde et renvoie la chaîne « Bonjour, le monde ! » :

use GuzzleHttp\Promise\Promise;
use GuzzleHttp\Promise\Utils;

// Création d'une nouvelle promesse
$promise = new Promise(function () use (&$promise) {
    // Simulation d'une opération asynchrone
    usleep(1000000); // 1 seconde
    $promise->resolve('Bonjour, le monde !');
});

// Ajout d'un gestionnaire pour le succès
$promise->then(function ($value) {
    echo "Reçu : " . $value . PHP_EOL;
});

// Lancement de l'exécution de la promesse
Utils::queue()->add(function () use ($promise) {
    $promise->wait();
});

// Exécution de la file d'attente
Utils::queue()->run();

Cet exemple illustre le mécanisme de base : création d’une promesse, sa résolution (resolve) et le traitement du résultat via la méthode then.

4. Méthodes, fonctions et classes principales

Examinons 8 composants clés de la bibliothèque avec des descriptions détaillées et des exemples.

4.1. Classe GuzzleHttp\Promise\Promise

Signature : new Promise(callable $waitFn = null, callable $canceller = null)

Fonctionnement : Crée une nouvelle promesse. Accepte optionnellement une fonction d’attente ($waitFn), appelée lors de l’appel à la méthode wait(), et une fonction d’annulation ($canceller).