Comprendre cURL avec PHP 8.5 : Guide complet pour débutants

Lorsque l’on commence à travailler avec PHP, on finit toujours par rencontrer un moment où l’on doit communiquer avec un service externe. Cela peut être un système de paiement, une API météo, une base de données externe ou même un simple script sur un autre serveur. Dans tous ces cas, on a besoin d’ouvrir une porte entre notre script PHP et ce service. Cette porte, c’est cURL.

Derrière ce nom qui ressemble un peu à un mouvement de musculation se cache en réalité une bibliothèque très puissante permettant d’envoyer et de recevoir des données à travers différents protocoles, principalement HTTP et HTTPS. Avec la sortie de PHP 8.5, cURL est toujours présent, toujours plus performant, et surtout essentiel pour construire des applications modernes.

Dans ce guide, nous allons prendre le sujet depuis le début. L’objectif est que vous soyez à l’aise avec l’utilisation de cURL, même si vous n’avez jamais appelé une API de votre vie. Nous allons comprendre comment cela fonctionne, pourquoi on l’utilise, puis nous pratiquerons avec plusieurs exemples concrets.

Qu’est-ce que cURL exactement ?

cURL est avant tout une bibliothèque. On peut l’imaginer comme une boîte à outils qui permet de communiquer avec d’autres serveurs, généralement en faisant des requêtes HTTP. Une requête HTTP, c’est un message envoyé sur Internet disant en quelque sorte : « Bonjour, pourrais-tu me renvoyer telle information ? ».

Par exemple, lorsque vous visitez une page web, votre navigateur envoie une requête au serveur. Avec cURL, c’est PHP qui envoie cette requête à votre place, sans passer par votre navigateur.

Pourquoi est-ce utile ?
Parce que cela permet à votre code de récupérer automatiquement des données. Un site météo, par exemple, peut vous renvoyer la température actuelle en JSON. Une API de paiement peut vous indiquer si une transaction est valide. Un serveur interne peut vous fournir les informations d’un client. Et tout cela, sans affichage à l’écran, juste par échange de données.

Tout savoir sur le Format JSON.

cURL et PHP 8.5

Dans PHP, cURL n’est pas une simple fonction mais un ensemble d’outils regroupés dans l’extension cURL. Bonne nouvelle : sur la plupart des hébergements modernes et avec PHP 8.5, cette extension est activée par défaut.

Cependant, si vous travaillez en local (Wamp, Mamp, Xampp ou environnement Docker), vérifiez qu’elle est bien activée. Généralement, il suffit d’ouvrir votre fichier php.ini et vérifier qu’il n’y a pas de point-virgule devant la ligne :

extension=curl

L’une des forces de PHP 8.5 est d’améliorer la performance globale des extensions et d’optimiser l’exécution des requêtes réseau. Cela se ressent notamment dans les requêtes répétées ou dans les applications qui effectuent de nombreuses communications externes.

La liste des Nouveauté de PHP 8.5.

Faire sa première requête cURL

Pour bien comprendre, commençons par l’exemple le plus simple : récupérer le contenu d’une page web.

Voici un code complet :

<?php

$url = "https://example.com";

// Initialisation de cURL
$curl = curl_init($url);

// Indiquer que l'on souhaite récupérer le résultat sous forme de chaîne
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

// Exécuter la requête
$response = curl_exec($curl);

// Fermer cURL après utilisation
curl_close($curl);

// Afficher la réponse
echo $response;

Dans un premier temps, on initialise cURL avec l’URL cible. Ensuite, avec curl_setopt, on donne des options. Il en existe beaucoup, mais ici la principale est CURLOPT_RETURNTRANSFER, qui indique que nous souhaitons récupérer le résultat dans une variable au lieu de l’afficher directement à l’écran.

Puis on exécute avec curl_exec. Enfin, on ferme l’outil avec curl_close. C’est un peu comme ouvrir un fichier, le lire, puis le refermer.

À ce stade, on a déjà un script capable de récupérer le code source d’un site distant.

Comprendre le fonctionnement des options cURL

Si vous observez des tutoriels en ligne, vous verrez beaucoup de curl_setopt. Cela peut donner l’impression que cURL est compliqué. Mais en vérité, chaque option sert à modifier le comportement de la requête. On peut comparer cela à personnaliser son café dans un bar : on demande chaud, ou froid, du sucre, pas de sucre, avec de la mousse, etc.

Voici quelques options que l’on utilisera lors de ce guide :

• CURLOPT_URL : L’adresse à appeler
• CURLOPT_RETURNTRANSFER : Indique si la réponse est retournée ou affichée
• CURLOPT_POST : Permet de faire une requête POST
• CURLOPT_POSTFIELDS : Permet d’envoyer des données dans une requête POST
• CURLOPT_HTTPHEADER : Permet d’ajouter des en-têtes HTTP (par exemple pour une API)
• CURLOPT_TIMEOUT : Temps maximum d’attente avant interruption
• CURLOPT_SSL_VERIFYPEER : Vérifie le certificat SSL du serveur

Chaque option s’ajuste en fonction de l’objectif de la requête. Et comme tout outil, plus on pratique, plus cela devient naturel.

Envoyer des données avec une requête POST

Beaucoup d’API demandent d’envoyer des données. Par exemple, pour vous authentifier, ou envoyer un message, ou créer un utilisateur dans une base externe. Pour cela, on utilise une requête POST.

Voici comment faire :

<?php

$url = "https://example.com/api/login";

$data = [
    "email" => "[email protected]",
    "password" => "monSuperMotDePasse"
];

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Ici, CURLOPT_POST indique que l’on envoie des données. CURLOPT_POSTFIELDS permet de transmettre ces données.

On utilise http_build_query car la plupart des API attendent des données encodées par formulaire.

Lors de la connexion d’un site vitrine à un système de réservation en ligne, l’API de ce service était… disons, capricieuse. La documentation était floue, les exemples incomplets. Pourtant, grâce à cURL, j’ai pu tester chaque requête étape par étape, comme un enquêteur qui relie les indices un à un. À la fin, voir le calendrier se mettre à jour automatiquement sur le site fut un moment de satisfaction mémorable. Comme quoi, même derrière des lignes de code, il y a parfois de petites victoires personnelles.

Envoyer des en-têtes HTTP avec cURL

Dans le monde des API modernes, il est très courant d’utiliser des en-têtes HTTP (qu’on appelle aussi Headers). Ils servent à transmettre des informations supplémentaires à propos de la requête. Par exemple, l’authentification, le type de données envoyées, ou encore votre clé d’API.

Pensez à toujours Sécuriser vos Header HTTP.

Imaginons que vous travailliez avec une API qui nécessite un token d’authentification. Vous devrez alors envoyer un en-tête comme :

Authorization: Bearer VOTRE_TOKEN

Voici comment faire en PHP avec cURL :

<?php

$url = "https://example.com/api/user";

$headers = [
    "Authorization: Bearer VOTRE_TOKEN_ICI",
    "Accept: application/json"
];

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Dans cet exemple, nous avons ajouté l’option CURLOPT_HTTPHEADER pour définir une liste d’en-têtes qui seront envoyés avec la requête. C’est essentiel, car la majorité des API modernes utilisent principalement ce système d’authentification.

Et si vous oubliez l’en-tête, l’API vous retournera souvent un beau message d’erreur du style : « Unauthorized » ou « Missing Token ». Cela peut surprendre la première fois, mais c’est absolument normal.

Manipuler les réponses JSON

La plupart des réponses envoyées par les API sont aujourd’hui au format JSON. JSON est un format d’échange de données simple, lisible et très pratique, car il s’intègre naturellement avec la façon dont PHP structure ses tableaux.

Voici un exemple classique de réponse JSON :

{
    "id": 42,
    "nom": "Dupont",
    "email": "[email protected]"
}

Pour traiter cette réponse dans votre script en PHP 8.5, vous utiliserez la fonction json_decode :

<?php

$response = curl_exec($curl);
$data = json_decode($response, true);

echo $data["nom"];

L’argument true permet de convertir le JSON en tableau PHP associatif. Sans cet argument, vous obtiendrez un objet. Cela fonctionne aussi, mais pour un débutant, le tableau est souvent plus simple à gérer.

Et là, vous pouvez manipuler les données comme si elles venaient de votre propre base.

Des formations informatique pour tous !

Débutant ou curieux ? Apprenez le développement web, le référencement, le webmarketing, la bureautique, à maîtriser vos appareils Apple et bien plus encore…

Formateur indépendant, professionnel du web depuis 2006, je vous accompagne pas à pas et en cours particulier, que vous soyez débutant ou que vous souhaitiez progresser. En visio, à votre rythme, et toujours avec pédagogie.

Découvrez mes formations Qui suis-je ?

Gérer les erreurs cURL (très important)

Dans le monde réel, tout ne se passe pas toujours comme prévu. Un serveur peut être inaccessible, votre clé d’API peut être incorrecte, la connexion peut être trop lente… Bref, votre requête cURL peut échouer. Et si vous ne testez pas les erreurs, vous ne saurez pas pourquoi.

Heureusement, cURL propose des fonctions pour récupérer les messages d’erreur :

<?php

$response = curl_exec($curl);

if ($response === false) {
    echo "Erreur cURL : " . curl_error($curl);
} else {
    echo $response;
}

curl_close($curl);

Ce simple test peut vous faire économiser des heures. Une fois, par exemple, j’ai passé une journée à comprendre pourquoi une API refusait mes appels. À la fin, le message d’erreur indiquait simplement que j’avais oublié un « s » dans l’URL. Un détail minuscule… mais fondamental.

cURL et PHP 8.5 : Quoi de nouveau ?

PHP 8.5 améliore cURL essentiellement sur le plan des performances et de la gestion des erreurs.

1. Traitement plus rapide : les requêtes réseau sont désormais exécutées avec un meilleur pipeline interne, réduisant les micro-latences.
2. Messages d’erreurs plus explicites : finies les erreurs floues « error 28 » incompréhensibles sans documentation. PHP 8.5 permet une traduction plus claire des erreurs cURL.
3. Support amélioré pour HTTP/3 : certaines API modernes commencent à migrer vers HTTP/3. cURL dans PHP 8.5 joue mieux avec ce protocole.

Vous n’avez rien à faire manuellement pour en profiter. Cela vient « gratuitement » avec votre version de PHP.

Avec l’arrivée de PHP 8.5, cURL ne change pas radicalement son fonctionnement, mais plusieurs améliorations importantes rendent son utilisation plus fluide, plus rapide et plus fiable. Comprendre ces nouveautés permet de mieux optimiser vos échanges avec les serveurs externes et d’éviter certains pièges que l’on rencontre souvent en production.

Pour bien saisir l’impact de ces nouveautés, regardons-les une à une, puis voyons comment les utiliser dans des cas concrets.

Des messages d’erreurs plus précis

Jusqu’à PHP 8.4, lorsqu’une requête cURL échouait, on se retrouvait souvent avec un message d’erreur un peu cryptique. Par exemple :

cURL error 28: Operation timed out after 5001 milliseconds

Ce message indiquait un dépassement de temps, mais on devait parfois aller chercher dans la documentation cURL pour comprendre exactement ce qui s’était passé.

Avec PHP 8.5, lorsque cURL rencontre une erreur, PHP renvoie désormais un message plus lisible, souvent accompagné d’une description plus claire. Cela facilite énormément le débogage.

Exemple :

$response = curl_exec($curl);

if ($response === false) {
    $errorCode = curl_errno($curl);
    $errorMessage = curl_strerror($errorCode);
    echo "Erreur cURL ($errorCode) : $errorMessage";
}

Ici, curl_strerror() renvoie un message explicite, que l’on peut comprendre sans documentation externe. Cela paraît simple, mais dans la pratique, c’est un gain de temps colossal.

Un meilleur support de HTTP/3

Le web évolue, les protocoles aussi. HTTP/3 commence doucement à être adopté, notamment par les grandes plateformes (Google, Cloudflare, certains CDN modernes…). cURL dans PHP 8.5 améliore sa compatibilité avec ce protocole basé sur QUIC, plus rapide et plus fiable sur les réseaux instables.

Même si tous les serveurs ne l’utilisent pas encore, PHP 8.5 est prêt.

Exemple d’une requête utilisant HTTP/3 (si le serveur le supporte) :

curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_3);

Si le serveur n’accepte pas HTTP/3, cURL basculera automatiquement en HTTP/2 ou HTTP/1.1. Vous bénéficiez ainsi du meilleur protocole disponible, sans travail supplémentaire.

De meilleures performances sur les requêtes répétées

Si votre application envoie des requêtes cURL en série, par exemple pour appeler plusieurs API dans une même page, PHP 8.5 optimise l’ouverture et la fermeture des connexions réseau. Résultat : moins de micro-latences, un chargement plus fluide, et une consommation CPU réduite.

Cela se voit particulièrement lorsque vous utilisez une boucle.

Avant, certaines requêtes pouvaient provoquer des ralentissements imperceptibles individuellement, mais visibles dans l’ensemble :

foreach ($urls as $url) {
    $curl = curl_init($url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($curl);
    curl_close($curl);
}

Avec PHP 8.5, ce même code est simplement plus rapide, sans changement.

Amélioration de curl_multi_exec pour les appels parallèles

Lorsque vous devez appeler plusieurs API en même temps (par exemple, récupérer plusieurs informations depuis différents services), vous pouvez utiliser curl_multi_exec, qui permet d’exécuter plusieurs requêtes simultanément.

PHP 8.5 offre une meilleure gestion interne de ces requêtes parallèles, ce qui réduit les temps d’attente.

Exemple simplifié :

$multi = curl_multi_init();

$curl1 = curl_init("https://example.com/api/user");
$curl2 = curl_init("https://example.com/api/stats");

curl_setopt($curl1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl2, CURLOPT_RETURNTRANSFER, true);

curl_multi_add_handle($multi, $curl1);
curl_multi_add_handle($multi, $curl2);

$running = null;
do {
    curl_multi_exec($multi, $running);
} while ($running);

$response1 = curl_multi_getcontent($curl1);
$response2 = curl_multi_getcontent($curl2);

curl_multi_remove_handle($multi, $curl1);
curl_multi_remove_handle($multi, $curl2);
curl_multi_close($multi);

Résultat : deux requêtes exécutées en parallèle au lieu d’enchaînées. Dans PHP 8.5, ce mécanisme est désormais plus fluide, plus stable et mieux géré.

Meilleure gestion SSL par défaut

cURL dans PHP 8.5 vérifie plus strictement les certificats SSL. C’est une bonne chose pour la sécurité, notamment lorsqu’on manipule des API sensibles.

Si votre environnement de développement local ne dispose pas encore des certificats CA à jour, vous pourriez voir des erreurs du type :

SSL certificate problem: unable to get local issuer certificate

La solution : configurer l’option suivante pendant le développement uniquement :

curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);

Mais en production, il est indispensable de la laisser à true.

Exemple avancé : Appeler une API REST qui crée un utilisateur

Prenons maintenant un exemple pratique, plus concret. Imaginons que vous souhaitiez créer un utilisateur via une API REST, en envoyant des données JSON cette fois-ci.

<?php

$url = "https://example.com/api/users";

$data = [
    "nom" => "Martin",
    "email" => "[email protected]",
    "role" => "abonne"
];

$payload = json_encode($data);

$headers = [
    "Content-Type: application/json",
    "Authorization: Bearer VOTRE_TOKEN"
];

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($curl);

if ($response === false) {
    echo curl_error($curl);
} else {
    echo $response;
}

curl_close($curl);

Ici, la différence majeure est que nous envoyons volontairement du JSON. C’est très fréquent dans les API modernes.

Tableau récapitulatif

Si vous êtes arrivé jusqu’ici, vous avez désormais une vision claire et solide de l’utilisation de cURL avec PHP 8.5. Vous savez comment envoyer une requête simple, comment transmettre des données, comment manipuler des réponses JSON, comment envoyer des en-têtes HTTP pour les API sécurisées et comment gérer les erreurs.

Le plus important désormais est de pratiquer. Prenez une API publique, même quelque chose de simple comme l’API qui renvoie des blagues ou des citations, et testez. À chaque requête réussie, vous construirez votre compréhension et votre confiance.

Et souvenez-vous : programmer, c’est souvent une affaire de petits pas. On tâtonne, on teste, on ajuste. Puis un jour, tout devient fluide.

Alban

Fondateur de l’agence Créa-troyes.
Intervenant en Freelance.
Contactez-moi

crea-troyes.fr