PHP : l'extension cURL

Date de publication : 12/06/2007

Par julp (Autres articles)
 

1. Installation

1.1. Windows

extension=php_curl.dll

1.2. Unix/Linux

1.2.1. Statique

./configure --prefix=/usr/local/php ... --with-curl
make
make install

1.2.2. Dynamique

cd /répertoire/des/sources/de/l/extension
phpize
./configure
make
make install

extension=curl.so

2. Vue d'ensemble

2.1. Les fonctions

• ressource curl_init([chaîne url]) :
  
  
  Initialise une nouvelle session cURL. Son seul paramètre url peut être omis mais il ne faudra pas oublier de l'indiquer par la suite avec la fonction curl_setopt, option CURLOPT_URL. Cette fonction renverra une ressource exploitable par les autres fonctions curl ou FALSE en cas d'erreur.
  
  
• booléen curl_setopt(ressource curl, entier option, variable valeur) :
  
  
  Définit le comportement de la session. Elle renvoie TRUE en cas de succès et FALSE si une erreur est rencontrée. Ces paramètres sont les suivants :
  • curl : la session cURL (résultat de l'appel à curl_init)
  • option : le nom de l'option sous la forme d'une constante, celles-ci commencent par CURLOPT_* et les principales seront présentées plus bas
  • valeur : la valeur à donner, son type (numérique, booléen, etc) est variable et est propre à l'option utilisée
  
  
• variable curl_exec(ressource curl) :
  
  
  Exécute la session cURL représentée par curl (résultat de la fonction curl_init). Toutes les informations nécessaires doivent être fournies au préalable avec la fonction curl_setopt. Elle retourne FALSE si une erreur survient et dans le cas contraire une valeur qui dépend de la valeur de l'option CURLOPT_RETURNTRANSFER. En effet, si cette option est fixée à FALSE (valeur par défaut), curl_exec renvoie alors TRUE sinon le résultat de la requête (du texte).
  
  
• rien curl_close(ressource curl) :
  
  
  Met fin à la session cURL désignée par le paramètre curl (résultat de la fonction curl_init) et libère les ressources allouées.
  
  

• chaîne curl_error(ressource curl) :
  
  
  Permet d'obtenir le texte décrivant la dernière erreur produite. S'il n'y en a pas eu, vous récupérerez alors une chaîne vide. Notez que cette fonction attend la session cURL courante issue de la fonction curl_init, elle doit donc par conséquent être appelée avant curl_close.
  
  
• variable curl_getinfo(ressource curl [, entier option]) :
  
  
  Fournit diverses informations concernant la dernière session indiquée par le paramètre curl. Si l'argument option est fourni alors seule l'information correspondante sera retournée et s'il est omis vous les obtiendrez toutes sous la forme d'un tableau associatif.
  
  
  Le paramètre option peut prendre l'une des valeurs suivantes sous les traits d'une constante :
  
  

  Nom	Description
  CURLINFO_EFFECTIVE_URL	Dernière URL effective utilisée.
  CURLINFO_HTTP_CODE	Code HTTP de la dernière réponse reçue. La valeur sera nulle si aucune réponse n'a (encore) été reçue.
  CURLINFO_FILETIME	Timestamp indiquant la date du fichier distant. La valeur -1 sera renvoyée si cette information n'est pas disponible et ce quelqu'en soit la raison.
  CURLINFO_TOTAL_TIME	Durée totale exprimée en secondes du précédent transfert (ceci inclue toutes les étapes de la connexion comme la résolution d'adresse).
  CURLINFO_NAMELOOKUP_TIME	Temps (en secondes) mis depuis le début (de la fonction curl_exec) jusqu'à la résolution de nom.
  CURLINFO_CONNECT_TIME	Temps mis en secondes depuis le début à l'établissement de la connexion avec l'hôte distant ou le proxy.
  CURLINFO_PRETRANSFER_TIME	Délai (en secondes) séparant le début au début du transfert. Cette étape inclue l'envoi des pré-commandes comme le permet l'option CURLOPT_QUOTE, par exemple.
  CURLINFO_STARTTRANSFER_TIME	Temps, en secondes, écoulé entre le début et l'envoi du premier octet du transfert.
  CURLINFO_REDIRECT_TIME	Durée totale du transfert incluant les différentes redirections. La valeur sera nulle si la requête n'a fait l'objet d'aucune redirection.
  CURLINFO_REDIRECT_COUNT	Nombre de redirections suivies.
  CURLINFO_SIZE_UPLOAD	Nombre d'octets envoyés.
  CURLINFO_SIZE_DOWNLOAD	Nombre d'octets reçus pour le dernier transfert.
  CURLINFO_SPEED_DOWNLOAD	Vitesse de téléchargement moyenne mesurée en octets/seconde.
  CURLINFO_SPEED_UPLOAD	Vitesse d'envoi moyenne exprimée en octets/seconde.
  CURLINFO_HEADER_SIZE	En octets, taille totale de tous les en-têtes reçus.
  CURLINFO_REQUEST_SIZE	Taille totale des requêtes effectuées (inclue les pages de redirection si CURLOPT_FOLLOWLOCATION est à TRUE). Cette information ne concerne que le protocole HTTP.
  CURLINFO_SSL_VERIFYRESULT	Résultat de la vérification de la certification demandée via l'option CURLOPT_SSL_VERIFYPEER.
  CURLINFO_CONTENT_LENGTH_DOWNLOAD	Valeur lue et correspondant au champ Content-Length dans la réponse.
  CURLINFO_CONTENT_LENGTH_UPLOAD	Taille spécifiée pour l'envoi (c'est à dire à la valeur de l'option CURLOPT_INFILESIZE).
  CURLINFO_CONTENT_TYPE	La valeur de l'en-tête Content-Type telle qu'elle a été lue. Vous pouvez obtenir la valeur NULL si le protocole ne gère pas cette en-tête ou si le serveur en a envoyé une qui s'avère être invalide.

  
  
  En revanche si vous n'utilisez pas ce deuxième paramètre, voilà la forme que prendra le tableau ainsi renvoyé par la fonction curl_getinfo :

  Array ( // Voir ci-dessus la description de la constante : 'url' => 'http://www.developpez.com/', // CURLINFO_EFFECTIVE_URL 'content_type' => 'text/html', // CURLINFO_CONTENT_TYPE 'http_code' => 200, // CURLINFO_HTTP_CODE 'header_size' => 145, // CURLINFO_HEADER_SIZE 'request_size' => 58, // CURLINFO_REQUEST_SIZE 'filetime' => -1, // CURLINFO_FILETIME 'ssl_verify_result' => 0, // CURLINFO_SSL_VERIFYRESULT 'redirect_count' => 0, // CURLINFO_REDIRECT_COUNT 'total_time' => 0.125, // CURLINFO_TOTAL_TIME 'namelookup_time' => 0, // CURLINFO_NAMELOOKUP_TIME 'connect_time' => 0.052, // CURLINFO_CONNECT_TIME 'pretransfer_time' => 0.052, // CURLINFO_PRETRANSFER_TIME 'size_upload' => 0, // CURLINFO_SIZE_UPLOAD 'size_download' => 0, // CURLINFO_SPEED_DOWNLOAD 'speed_download' => 0, // CURLINFO_SPEED_DOWNLOAD 'speed_upload' => 0, // CURLINFO_SPEED_UPLOAD 'download_content_length' => 0, // CURLINFO_CONTENT_LENGTH_DOWNLOAD 'upload_content_length' => 0, // CURLINFO_CONTENT_LENGTH_UPLOAD 'starttransfer_time' => 0.124, // CURLINFO_STARTTRANSFER_TIME 'redirect_time' => 0 // CURLINFO_REDIRECT_TIME )

2.2. Les options

3. Utilisation

3.1. Le protocole HTTP

3.1.1. Vérifier l'existence d'une URL

• 200 (OK) : la requête aboutie normalement
• 301 (Moved Permanently) : la ressource visée a été définitivement déplacée, cette URL est obsolète
• 302 (Temporary Redirect) : la page est temporairement accessible via une autre URL

function http_check_url($url, $timeout = 10)
{
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_TIMEOUT, $timeout);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
    curl_setopt($ch, CURLOPT_NOBODY, TRUE);
    if (strpos($url, 'https://') === 0) {
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); // On ne vérifie que l'existence de la page
    }
    if (!curl_exec($ch)) {
        return FALSE;
    }
    $ret = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return in_array($ret, array(200, 301, 302));
}

// Exemple d'utilisation :
define('OK', '<span style="color: green">OK</span>');
define('KO', '<span style="color: red">KO</span>');
$urls = array(
    'http://www.non-existant.fr',
    'http://www.developpez.com/',
    'http://php.developpez.com/faq/'
);
foreach ($urls as $u) {
    echo $u . ' : ' . (check_url($u) ? OK : KO) . '<br/>';
}

3.1.2. Récupérer le contenu d'une page

function http_fetch_url($url, $timeout = 10, $userpwd = '')
{
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_TIMEOUT, $timeout);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    if ($userpwd) {
        curl_setopt($ch, CURLOPT_USERPWD, $userpwd);
    }
    $data = curl_exec($ch);
    curl_close($ch);

    return $data;
}

// Exemple d'utilisation :
if (($content = fetch_url('http://www.monsite.fr/zone_privee/sqldump.php', 10, 'utilisateur:mot_de_passe')) === FALSE) {
    die("Une erreur est survenue");
} else {
    echo htmlentities($content);
}

Pour des raisons légales, vous êtes fortement invités à prendre préalablement contact avec les responsables des sites sur lesquels vous voudriez reprendre des informations.

3.1.3. Envoyer des données par la méthode POST

// Pour assurer la compatibilité avec les versions PHP 4
if (!function_exists('http_build_query')) {
    function http_build_query($formdata, $numeric_prefix = NULL, $arg_separator = '', $parent_key = '') {
        $ret = array();
        if (is_array($formdata)) {
            if (empty($arg_separator)) {
                $arg_separator = ini_get('arg_separator.output');
            }
            foreach ($formdata as $k => $v) {
                if (is_int($k) && $numeric_prefix != NULL) {
                    $k = $numeric_prefix . $k;
                }
                if ($parent_key != '') {
                    $k = sprintf('%s[%s]', $parent_key, $k);
                }
                if (is_array($v)) {
                    array_push($ret, http_build_query($v, NULL, $arg_separator, $k));
                } elseif (is_object($v)) {
                    array_push($ret, http_build_query(get_object_vars($v), NULL, $arg_separator, $k));
                } else {
                    array_push($ret, urlencode($k) . '=' . urlencode($v));
                }
            }
        }
        return implode($arg_separator, $ret);
    }
}

// Faire suivre les données POST à une autre page
$ch = curl_init('http://www.monsite.fr/formulaire.html');
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($_POST));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$ret = curl_exec($ch);
if (!$ret) {
    echo curl_error($ch);
} else {
    echo $ret;
}
curl_close($ch);

• Vous n'avez pas à vous soucier de la forme des données : elles seront regroupées et encodées en interne par cURL
• Cela permet l'upload de fichiers : tout paramètre dont le nom commence par une arobase et correspondant à un fichier local sera joint

// Données à envoyer
$post = array(
    // La zone de texte "description"
    'description' => "Photo n°1 de mon week-end en Bretagne.\r\nPique-nique dans la forêt de Broceliande.",
    // Le fichier à uploader sous "photo"
    'photo'      => '@' . realpath('P1010001.JPG')
);

// On effectue la requête avec cURL
$ch = curl_init('http://www.monsite.fr/envoi_photo.php');
curl_setopt($ch, CURLOPT_NOBODY, TRUE);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$ret = curl_exec($ch);
if (!$ret) {
    echo curl_error($ch);
} else {
    echo 'Envoi OK !';
}
curl_close($ch);

3.1.4. Débuter une session puis la réutiliser

define('LOGIN', 'julp');
define('PASSWORD', 'mdp');
define('AUTHENTIFICATION', 'http://localhost/curl/session/login.php');
define('PAGE_PRIVEE', 'http://localhost/curl/session/admin.php');

$sid = '';

/**
 * Première connexion : authentification
 **/
$ch = curl_init(AUTHENTIFICATION);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    array(
        'login' => LOGIN,
        'mdp' => PASSWORD
    )
);
curl_setopt($ch, CURLOPT_COOKIEJAR, realpath('cookie.txt'));
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_COOKIESESSION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$ret = curl_exec($ch);
if ($ret === FALSE) {
    die(curl_error());
}
curl_close($ch);
if (preg_match('/(PHPSESSID=[0-9a-z,-]{32,40})/i', $ret, $m)) {
    $sid = '?' . $m[1];
} else if (preg_match('#<input\s+type="hidden"\s+name="([^\r\n\t <>\'"\\\]+)"\s+value="([0-9a-z,-]{32,40})"\s*/?>#i', $ret, $m)) {
    $sid = '?' . $m[1] . '=' . $m[2];
}

/**
 * Deuxième partie : réutilisation de la session sur une page tierce
 **/
$ch = curl_init(PAGE_PRIVEE . $sid);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_COOKIEFILE, realpath('cookie.txt'));
$ret = curl_exec($ch);
if ($ret === FALSE) {
    die(curl_error());
}
curl_close($ch);
echo $ret;

Pour en savoir plus sur les sessions php (utilisation comme configuration), je vous invite à consulter l'article éponyme :  Les sessions en PHP.

3.1.5. Source : simplifier l'utilisation de cURL pour le protocole HTTP

class HTTPQuery
{
    /**
     * Tableau : les données POST qui seront envoyées (nom du champ => valeur)
     **/
    protected $_post;

    /**
     * Tableau des options cURL définies par l'utilisateur (option => valeur)
     **/
    protected $_options;

    /**
     * La ressource cURL
     **/
    protected $_ch;

    /**
     * Constructeur
     * @param url URL à laquelle la requête sera envoyée
     * @throws Exception si l'extension cURL n'est pas active
     **/
    public function __construct($url)
    {
        if (!extension_loaded('curl')) {
            throw new Exception("L'extension curl n'est pas disponible");
        }
        $this->_ch = curl_init($url);
        $this->_options = array();
    }

    /**
     * Obtenir la valeur des options cURL avec la syntaxe $ojet->CURLOPT_X définie par l'utilisateur
     * @param nom le nom de l'option cURL
     * @return NULL si l'option n'a pas été définie sinon sa valeur
     **/
    public function __get($nom)
    {
        $resultat = NULL;
        if (defined($nom)) {
            $valeur = constant($nom);
            if (isset($this->_options[$valeur])) {
                $resultat = $this->_options[$valeur];
            }
        }
        return $resultat;
    }

    /**
     * Fixer les valeurs des options cURL avec la syntaxe $objet->CURLOPT_X = Y
     * @param nom    le nom de l'option cURL (constantes CURLOPT_*)
     * @param valeur la nouvelle valeur de l'option