XVI. CURL

Introduction

PHP supporte libcurl, une bibliothèque créée par Daniel Stenberg, qui vous permet de vous connecter, de communiquer avec de nombreux serveurs, grâce à de nombreux protocoles. libcurl supporte actuellement les protocoles suivants : HTTP, HTTPS, FTP, gopher, telnet, dict, file, et LDAP. libcurl supporte aussi les certificats HTTPS, les POST HTTP, PUT HTTP, le chargement par FTP (ce qui peut être fait par l'extension FTP), les chargements par formulaire HTTP, les proxies, les cookies et l'identification par mot de passe et nom d'utilisateur.

Ces fonctions ont été ajoutées en PHP 4.0.2.

Pré-requis

Pour pouvoir utiliser les fonctions CURL, vous devez installer le package CURL. PHP requiert la version CURL 7.0.2-beta ou plus récente. PHP ne fonctionnera pas avec une version inférieure à la version 7.0.2-beta. En PHP 4.2.3, vous aurez besoin de CURL version 7.9.0 ou plus. A partir de PHP 4.3.0, vous aurez besoin de CURL version 7.9.8 ou plus. PHP 5.0.0 aura sûrement besoin d'une version de CURL supérieure à la 7.10.5.

Installation

Pour utiliser CURL depuis les scripts PHP, vous devez compiler celui-ci avec l'option --with-curl[=DIR] où DIR est le chemin jusqu'au dossier contenant les dossiers lib et include. Dans le dossier include il doit se trouver un dossier appelé curl, qui contient notamment les fichiers easy.h et curl.h. Il doit aussi se trouver un fichier nommé libcurl.a dans le dossier lib. A partir de PHP 4.3.0, vous pouvez aussi configurer PHP pour qu'il utilise curl comme gestionnaire d'URL avec l'option --with-curlwrappers.

Note aux utilisateurs Win32 : Afin d'activer ce module dans l'environnement Windows, vous devez copier les bibliothèques libeay32.dll et ssleay32.dll depuis le dossier DLL de PHP/Win32 dans le dossier SYSTEM de votre machine. (par exemple : C:\WINNT\SYSTEM32 ou C:\WINDOWS\SYSTEM).

Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

CURLOPT_DNS_USE_GLOBAL_CACHE (entier)

CURLOPT_DNS_CACHE_TIMEOUT (entier)

CURLOPT_FTPSSLAUTH (entier)

Disponible depuis PHP 5.1.0

CURLOPT_PORT (entier)

CURLOPT_FILE (entier)

CURLOPT_INFILE (entier)

CURLOPT_INFILESIZE (entier)

CURLOPT_URL (entier)

CURLOPT_PROXY (entier)

CURLOPT_VERBOSE (entier)

CURLOPT_HEADER (entier)

CURLOPT_HTTPHEADER (entier)

CURLOPT_NOPROGRESS (entier)

CURLOPT_NOBODY (entier)

CURLOPT_FAILONERROR (entier)

CURLOPT_UPLOAD (entier)

CURLOPT_POST (entier)

CURLOPT_FTPLISTONLY (entier)

CURLOPT_FTPAPPEND (entier)

CURLOPT_NETRC (entier)

CURLOPT_FOLLOWLOCATION (entier)

CURLOPT_FTPASCII (entier)

CURLOPT_PUT (entier)

CURLOPT_MUTE (entier)

CURLOPT_USERPWD (entier)

CURLOPT_PROXYUSERPWD (entier)

CURLOPT_RANGE (entier)

CURLOPT_TIMEOUT (entier)

CURLOPT_POSTFIELDS (entier)

CURLOPT_REFERER (entier)

CURLOPT_USERAGENT (entier)

CURLOPT_FTPPORT (entier)

CURLOPT_FTP_USE_EPSV (entier)

CURLOPT_LOW_SPEED_LIMIT (entier)

CURLOPT_LOW_SPEED_TIME (entier)

CURLOPT_RESUME_FROM (entier)

CURLOPT_COOKIE (entier)

CURLOPT_SSLCERT (entier)

CURLOPT_SSLCERTPASSWD (entier)

CURLOPT_WRITEHEADER (entier)

CURLOPT_SSL_VERIFYHOST (entier)

CURLOPT_COOKIEFILE (entier)

CURLOPT_SSLVERSION (entier)

CURLOPT_TIMECONDITION (entier)

CURLOPT_TIMEVALUE (entier)

CURLOPT_CUSTOMREQUEST (entier)

CURLOPT_STDERR (entier)

CURLOPT_TRANSFERTEXT (entier)

CURLOPT_RETURNTRANSFER (entier)

CURLOPT_QUOTE (entier)

CURLOPT_POSTQUOTE (entier)

CURLOPT_INTERFACE (entier)

CURLOPT_KRB4LEVEL (entier)

CURLOPT_HTTPPROXYTUNNEL (entier)

CURLOPT_FILETIME (entier)

CURLOPT_WRITEFUNCTION (entier)

CURLOPT_READFUNCTION (entier)

CURLOPT_PASSWDFUNCTION (entier)

CURLOPT_HEADERFUNCTION (entier)

CURLOPT_MAXREDIRS (entier)

CURLOPT_MAXCONNECTS (entier)

CURLOPT_CLOSEPOLICY (entier)

CURLOPT_FRESH_CONNECT (entier)

CURLOPT_FORBID_REUSE (entier)

CURLOPT_RANDOM_FILE (entier)

CURLOPT_EGDSOCKET (entier)

CURLOPT_CONNECTTIMEOUT (entier)

CURLOPT_SSL_VERIFYPEER (entier)

CURLOPT_CAINFO (entier)

CURLOPT_CAPATH (entier)

CURLOPT_COOKIEJAR (entier)

CURLOPT_SSL_CIPHER_LIST (entier)

CURLOPT_BINARYTRANSFER (entier)

CURLOPT_NOSIGNAL (entier)

CURLOPT_PROXYTYPE (entier)

CURLOPT_BUFFERSIZE (entier)

CURLOPT_HTTPGET (entier)

CURLOPT_HTTP_VERSION (entier)

CURLOPT_SSLKEY (entier)

CURLOPT_SSLKEYTYPE (entier)

CURLOPT_SSLKEYPASSWD (entier)

CURLOPT_SSLENGINE (entier)

CURLOPT_SSLENGINE_DEFAULT (entier)

CURLOPT_SSLCERTTYPE (entier)

CURLOPT_CRLF (entier)

CURLOPT_ENCODING (entier)

CURLOPT_PROXYPORT (entier)

CURLOPT_UNRESTRICTED_AUTH (entier)

CURLOPT_FTP_USE_EPRT (entier)

CURLOPT_HTTP200ALIASES (entier)

CURLOPT_HTTPAUTH (entier)

CURLAUTH_BASIC (entier)

CURLAUTH_DIGEST (entier)

CURLAUTH_GSSNEGOTIATE (entier)

CURLAUTH_NTLM (entier)

CURLAUTH_ANY (entier)

CURLAUTH_ANYSAFE (entier)

CURLOPT_PROXYAUTH (entier)

CURLCLOSEPOLICY_LEAST_RECENTLY_USED (entier)

CURLCLOSEPOLICY_LEAST_TRAFFIC (entier)

CURLCLOSEPOLICY_SLOWEST (entier)

CURLCLOSEPOLICY_CALLBACK (entier)

CURLCLOSEPOLICY_OLDEST (entier)

CURLINFO_EFFECTIVE_URL (entier)

CURLINFO_HTTP_CODE (entier)

CURLINFO_HEADER_SIZE (entier)

CURLINFO_REQUEST_SIZE (entier)

CURLINFO_TOTAL_TIME (entier)

CURLINFO_NAMELOOKUP_TIME (entier)

CURLINFO_CONNECT_TIME (entier)

CURLINFO_PRETRANSFER_TIME (entier)

CURLINFO_SIZE_UPLOAD (entier)

CURLINFO_SIZE_DOWNLOAD (entier)

CURLINFO_SPEED_DOWNLOAD (entier)

CURLINFO_SPEED_UPLOAD (entier)

CURLINFO_FILETIME (entier)

CURLINFO_SSL_VERIFYRESULT (entier)

CURLINFO_CONTENT_LENGTH_DOWNLOAD (entier)

CURLINFO_CONTENT_LENGTH_UPLOAD (entier)

CURLINFO_STARTTRANSFER_TIME (entier)

CURLINFO_CONTENT_TYPE (entier)

CURLINFO_REDIRECT_TIME (entier)

CURLINFO_REDIRECT_COUNT (entier)

CURL_VERSION_IPV6 (entier)

CURL_VERSION_KERBEROS4 (entier)

CURL_VERSION_SSL (entier)

CURL_VERSION_LIBZ (entier)

CURLVERSION_NOW (entier)

CURLE_OK (entier)

CURLE_UNSUPPORTED_PROTOCOL (entier)

CURLE_FAILED_INIT (entier)

CURLE_URL_MALFORMAT (entier)

CURLE_URL_MALFORMAT_USER (entier)

CURLE_COULDNT_RESOLVE_PROXY (entier)

CURLE_COULDNT_RESOLVE_HOST (entier)

CURLE_COULDNT_CONNECT (entier)

CURLE_FTP_WEIRD_SERVER_REPLY (entier)

CURLE_FTP_ACCESS_DENIED (entier)

CURLE_FTP_USER_PASSWORD_INCORRECT (entier)

CURLE_FTP_WEIRD_PASS_REPLY (entier)

CURLE_FTP_WEIRD_USER_REPLY (entier)

CURLE_FTP_WEIRD_PASV_REPLY (entier)

CURLE_FTP_WEIRD_227_FORMAT (entier)

CURLE_FTP_CANT_GET_HOST (entier)

CURLE_FTP_CANT_RECONNECT (entier)

CURLE_FTP_COULDNT_SET_BINARY (entier)

CURLE_PARTIAL_FILE (entier)

CURLE_FTP_COULDNT_RETR_FILE (entier)

CURLE_FTP_WRITE_ERROR (entier)

CURLE_FTP_QUOTE_ERROR (entier)

CURLE_HTTP_NOT_FOUND (entier)

CURLE_WRITE_ERROR (entier)

CURLE_MALFORMAT_USER (entier)

CURLE_FTP_COULDNT_STOR_FILE (entier)

CURLE_READ_ERROR (entier)

CURLE_OUT_OF_MEMORY (entier)

CURLE_OPERATION_TIMEOUTED (entier)

CURLE_FTP_COULDNT_SET_ASCII (entier)

CURLE_FTP_PORT_FAILED (entier)

CURLE_FTP_COULDNT_USE_REST (entier)

CURLE_FTP_COULDNT_GET_SIZE (entier)

CURLE_HTTP_RANGE_ERROR (entier)

CURLE_HTTP_POST_ERROR (entier)

CURLE_SSL_CONNECT_ERROR (entier)

CURLE_FTP_BAD_DOWNLOAD_RESUME (entier)

CURLE_FILE_COULDNT_READ_FILE (entier)

CURLE_LDAP_CANNOT_BIND (entier)

CURLE_LDAP_SEARCH_FAILED (entier)

CURLE_LIBRARY_NOT_FOUND (entier)

CURLE_FUNCTION_NOT_FOUND (entier)

CURLE_ABORTED_BY_CALLBACK (entier)

CURLE_BAD_FUNCTION_ARGUMENT (entier)

CURLE_BAD_CALLING_ORDER (entier)

CURLE_HTTP_PORT_FAILED (entier)

CURLE_BAD_PASSWORD_ENTERED (entier)

CURLE_TOO_MANY_REDIRECTS (entier)

CURLE_UNKNOWN_TELNET_OPTION (entier)

CURLE_TELNET_OPTION_SYNTAX (entier)

CURLE_OBSOLETE (entier)

CURLE_SSL_PEER_CERTIFICATE (entier)

CURLE_GOT_NOTHING (entier)

CURLE_SSL_ENGINE_NOTFOUND (entier)

CURLE_SSL_ENGINE_SETFAILED (entier)

CURLE_SEND_ERROR (entier)

CURLE_RECV_ERROR (entier)

CURLE_SHARE_IN_USE (entier)

CURLE_SSL_CERTPROBLEM (entier)

CURLE_SSL_CIPHER (entier)

CURLE_SSL_CACERT (entier)

CURLE_BAD_CONTENT_ENCODING (entier)

CURLE_LDAP_INVALID_URL (entier)

CURLE_FILESIZE_EXCEEDED (entier)

CURLE_FTP_SSL_FAILED (entier)

CURLFTPAUTH_DEFAULT (entier)

Disponible depuis PHP 5.1.0

CURLFTPAUTH_SSL (entier)

Disponible depuis PHP 5.1.0

CURLFTPAUTH_TLS (entier)

Disponible depuis PHP 5.1.0

CURLPROXY_HTTP (entier)

CURLPROXY_SOCKS5 (entier)

CURL_NETRC_OPTIONAL (entier)

CURL_NETRC_IGNORED (entier)

CURL_NETRC_REQUIRED (entier)

CURL_HTTP_VERSION_NONE (entier)

CURL_HTTP_VERSION_1_0 (entier)

CURL_HTTP_VERSION_1_1 (entier)

CURLM_CALL_MULTI_PERFORM (entier)

CURLM_OK (entier)

CURLM_BAD_HANDLE (entier)

CURLM_BAD_EASY_HANDLE (entier)

CURLM_OUT_OF_MEMORY (entier)

CURLM_INTERNAL_ERROR (entier)

CURLMSG_DONE (entier)

Exemples

Une fois que vous avez compilé PHP avec le support CURL, vous pouvez commencer à l'exploiter avec vos scripts PHP. Le principe de fonctionnement est d'initialiser une session CURL avec curl_init(), puis de choisir toutes vos options de transfert avec curl_setopt(), puis d'exécuter la session avec curl_exec() et de finir votre session avec curl_close(). Voici un exemple d'utilisation des fonctions CURL, qui récupère la page principale de example.com dans un fichier :

Exemple 1. Utilisation de CURL pour récupérer une page

<?php

$ch
= curl_init("http://www.example.com/");
$fp = fopen("example_homepage.txt", "w");

curl_setopt($ch, CURLOPT_FILE, $fp);
curl_setopt($ch, CURLOPT_HEADER, 0);

curl_exec($ch);
curl_close($ch);
fclose($fp);
?>

Table des matières
curl_close -- Ferme une session CURL
curl_copy_handle --  Copie une resource curl avec toutes ses préférences
curl_errno --  Retourne un entier représentant le dernier message d'erreur CURL
curl_error --  Retourne une chaîne contenant le dernier message d'erreur CURL
curl_exec -- Exécute une session CURL
curl_getinfo --  Lit les informations détaillant un transfert CURL
curl_init -- Initialise une session CURL
curl_multi_add_handle --  Ajoute une ressource cURL à un cURL multiple
curl_multi_close --  Termine un jeu de sessions cURL
curl_multi_exec --  Exécute les sous-requêtes de la session cURL
curl_multi_getcontent --  Retourne le contenu obtenu avec l'option CURLOPT_RETURNTRANSFER
curl_multi_info_read --  Lit les informations sur les transferts actuels
curl_multi_init --  Retourne un nouveau cURL multiple
curl_multi_remove_handle --  Retire un cURL multiple d'un jeu de cURL
curl_multi_select --  Retourne les sockets associées à cURL, pour utilisation
curl_setopt -- Modifie une option de transfert CURL
curl_version -- Retourne la version courante de CURL