Manuel PHP
Précédent |  | Suivant

# curl_setopt

(PHP 4 >= 4.0.2, PHP 5)

curl_setopt -- Modifie une option de transfert CURL

## Description

bool curl_setopt ( resource ch, integer option, mixed value)

curl_setopt() fixe les options de transfert de la session CURL identifiée par ch. option est le nom de l'option à fixer, et value est sa valeur.

value doit être de type "long" pour les options suivantes (spécifiée par option) :

- CURLOPT_INFILESIZE : Lorsque vous téléchargez un fichier sur un site distant, cette option sert à indiquer à PHP la taille maximale du fichier attendu.

- CURLOPT_VERBOSE : Choisissez une valeur non nulle pour que CURL vous affiche tous les événements. Ecrit la sortie sur stderr ou dans le fichier spécifié en utilisant CURLOPT_STDERR.

- CURLOPT_HEADER : Choisissez une valeur non nulle pour que CURL inclut l'en-tête dans la valeur de retour.

- CURLOPT_NOPROGRESS : Choisissez une valeur non nulle pour que PHP n'affiche pas l'état des transferts CURL.

  > Note : PHP choisit automatiquement une valeur non nulle. Ne changez cette valeur que le temps du déboguage.

- CURLOPT_NOBODY : Choisissez une valeur non nulle pour que le corps du transfert ne soit pas inclus dans la valeur de retour.

- CURLOPT_FAILONERROR : Choisissez une valeur non nulle pour que PHP traite silencieusement les codes HTTP supérieurs à 300. Le comportement par défaut est de retourner la page normalement, en ignorant ce code.

- CURLOPT_UPLOAD : Choisissez une valeur non nulle pour que PHP prépare un chargement.

- CURLOPT_POST : Choisissez une valeur non nulle pour que PHP fasse un HTTP POST. Un POST est un encodage normal "application/x-www-from-url", utilisé couramment par les formulaires HTML.

- CURLOPT_FTPLISTONLY : Choisissez une valeur non nulle pour que PHP ne fasse que lister les noms d'un dossier FTP.

- CURLOPT_FTPAPPEND : Choisissez une valeur non nulle pour que PHP concatène le fichier distant, plutôt que de l'écraser.

- CURLOPT_NETRC : Choisissez une valeur non nulle pour que PHP analyse votre fichier `~./netrc` et utilise votre nom de compte et mot de passe sur le site distant que vous souhaitez contacter.

- CURLOPT_FOLLOWLOCATION : Choisissez une valeur non nulle pour suivre toutes les en-têtes "Location: " que le serveur envoie dans les en-têtes HTTP (notez que cette fonction est récursive et que PHP suivra toutes les en-têtes "Location: " qu'il trouvera).

- CURLOPT_PUT : Choisissez une valeur non nulle pour que pour chargement se fasse par HTTP PUT. Le fichier à charger doit être fixé avec les options `CURLOPT_INFILE` et `CURLOPT_INFILESIZE`.

- CURLOPT_MUTE : Choisissez une valeur non nulle pour que PHP soit totalement silencieux concernant toutes les fonctions CURL.

- CURLOPT_TIMEOUT : Passez un entier "long" comme paramètre qui représente le temps maximum d'exécution de la fonction CURL.

- CURLOPT_LOW_SPEED_LIMIT : Passez un entier long qui représente la vitesse minimale en octets par secondes en dessous de laquelle, et pendant `CURLOPT_LOW_SPEED_TIME` secondes, PHP considérera qu'elle est trop lente, et annulera le transfert.

- CURLOPT_LOW_SPEED_TIME : Passez un entier "long" qui représente le temps en secondes, qui, si la vitesse de transfert reste en dessous de `CURLOPT_LOW_SPEED_LIMIT`, PHP considèrera que la connexion est trop lente, et l'annulera.

- CURLOPT_RESUME_FROM : Passez un entier "long", qui représente l'offset, en octets, à partir duquel vous voulez commencer le transfert.

- CURLOPT_CAINFO: Passez le nom d'un fichier contenant un ou plusieurs certificats pour vérifier la concordance. Celà n'a de sens que si vous l'utilisez en combinaison de l'option CURLOPT_SSL_VERIFYPEER.

- CURLOPT_SSL_VERIFYPEER: Passez un entier long qui sera mis à 0 pour arrêter CURL de vérifier le certificat (CURL 7.10 démarre avec cette option à `TRUE` par défaut). Les certificats alternatifs peuvent être spécifiés avec l'option CURLOPT_CAINFO (ajouté dans CURL 7.9.8) ou un répertoire de certificat peut être spécifié avec l'option CURLOPT_CAPATH. Tout comme CURL 7.10, CURL installe un paquet par défaut. CURLOPT_SSL_VERIFYHOST doit aussi être positionnée à 1 ou 0 si CURLOPT_SSL_VERIFYPEER est désactivée (par défaut à 2).

- CURLOPT_SSLVERSION : Passez un entier "long" qui contient la version de SSL (2 ou 3) à utiliser. Par défaut, PHP essayera de le déterminer lui-même, bien que dans certains cas, il vous faudra le faire manuellement.

- CURLOPT_SSL_VERIFYHOST: Passez un entier "long" si CURL doit vérifier le nom "commun" du certificat dans une connexion SSL. Si vous spécifiez la valeur 1, nous vérifirons l'existence du nom commun, la valeur 2, nous nous assurerons qu'il correspond au nom d'hôte.

- CURLOPT_TIMECONDITION : Passez un entier "long" qui définit comment `CURLOPT_TIMEVALUE` est utilisé. Vous pouvez choisir entre les valeurs `TIMECOND_IFMODSINCE` ou `TIMECOND_ISUNMODSINCE`. C'est une fonctionnalité HTTP.

- CURLOPT_TIMEVALUE : Passez un entier "long" qui représente le temps en secondes depuis le 1er janvier 1970. Cette valeur sera utilisée comme spécifié dans l'option `CURLOPT_TIMEVALUE`. Par défaut, `TIMECOND_IFMODSINCE` sera utilisée.

- CURLOPT_RETURNTRANSFER: Définissez cette option à une valeur différente de zéro si vous voulez que CURL retourne directement le transfert au lieu de l'afficher.

- CURLOPT_NOSIGNAL: Définissez cette option à une valeur différente de zéro si vous voulez que CURL ignore toutes les fonctions CURL, ce qui cause l'envoi d'un signal au processus PHP. Activé par défaut dans les SAPIs multi-threadés, les options de timeout peut toujours être utilisées. Ajouté dans CURL 7.10.

- CURLOPT_DNS_USE_GLOBAL_CACHE: Définissez cette valeur à une valeur différente de zéro si vous voulez que CURL utilise un cache DNS global. Cette option n'est pas thread-safe et est activée par défaut.

- CURLOPT_DNS_CACHE_TIMEOUT: Passez un entier long comme paramètre qui représente le temps en seconde que CURL doit conserver les entrées DNS en mémoire. Cette option est définie à 120 (2minutes) par défaut.

- CURLOPT_PORT: Passezun entier long comme paramètre qui représente le numéro du port de connexion, à la place de la valeur par défaut utilisée par le protocole.

- CURLOPT_TRANSFERTEXT: Définissez cette option à une valeur différente de 0 si vous voulez que CURL utilise le mode ASCII pour les transferts FTP. Pour LDAP, il récupère les données en texte plein au lieu d'Html. Sur les systèmes WIndows, stdout ne sera pas définie en mode binaire.

- CURLOPT_FTPASCII: Un alias de CURLOPT_TRANSFERTEXT. Utilisez celui-là à la placeUse.

- CURLOPT_FTP_USE_EPSV: Définissez cette option à une valeur différente de 0 si vous voulez que CURL tente tout d'abord une commande EPSV pour les transferts FTP avant de revenir à une commande PASV. Définissez cette option à 0 pour désactiver EPSV.

- CURLOPT_HTTPPROXYTUNNEL: Définissez cette option à une valeur différente de 0 pour effectuer un tunnel à travers un proxy HTTP.

- CURLOPT_FILETIME: Définissez une valeur différente de 0 si vous voulez que CURL tente de récupérer la date de modification du document distant. Vous pouvez également retrouver cette valeur en utilisant l'option CURLINFO_FILETIME avec curl_getinfo().

- CURLOPT_MAXREDIRS: Passez un entier long comme valeur qui représente le nombre maximal de redirections HTTP à suivre. Utilisez cette option avec l'option CURLOPT_FOLLOWLOCATION.

- CURLOPT_MAXCONNECTS: Passez un entier long comme valeur représentant le nombre maximal de connexions persistentes autorisées. Lorsque la limite est atteinte, l'option CURLOPT_CLOSEPOLICY est utilisé pour afficher les connexions fermées.

- CURLOPT_CLOSEPOLICY: Définissez cette option à soit CURLCLOSEPOLICY_LEAST_RECENTLY_USED, soit CURLCLOSEPOLICY_OLDEST. Il y a trois autres constantes CURLCLOSEPOLICY_ mais CURL ne les supporte pas encore.

- CURLOPT_FRESH_CONNECT: Définissez cette option à une valeur différente de 0 pour forcer à utiliser une nouvelle connexion au lieu de celle en cache.

- CURLOPT_FORBID_REUSE: Définissez cette option à une valeur différente de 0 pour forcer la connexion à se fermer explicitement lorsque le processus est terminé et ne sera pas mise en cache pour être réutilisée.

- CURLOPT_CONNECTTIMEOUT: Définissez un entier long comme valeur représentant le nombre de secondes à attendre durant la tentative de connexion. Utilisez une valeur de 0 pour attendre indéfiniment.

- CURLOPT_BINARYTRANSFER: Définissez cette option à une valeur différente de 0 pour retourner la ligne affichée lorsque l'option CURLOPT_RETURNTRANSFER est utilisée.

- CURLOPT_PROXYTYPE: Définissez cette option à soit CURLPROXY_HTTP (par défaut) ou CURLPROXY_SOCKS5. Ceci a été ajouté en CURL 7.10.

- CURLOPT_BUFFERSIZE: Passez un entier long comme valeur représentant la taille du buffer à utiliser pour chaque lecture. Cependant, il n'y a aucune garantie que cette requête soit accomplie. Ceci a été ajouté en CURL 7.10.

- CURLOPT_HTTPGET: Définissez cette option à une valeur différente de 0 pour réinitialiser la méthode de requête HTTP à POST. Sachant que GET est la valeur par défaut, celà n'est uniquement nécessaire que si la méthode de requête a été changée.

- CURLOPT_HTTP_VERSION: Définissez cette option à CURL_HTTP_VERSION_NONE (défaut, laisse CURL décider la version à utiliser), CURL_HTTP_VERSION_1_0 (force HTTP/1.0), or CURL_HTTP_VERSION_1_1 (force HTTP/1.1).

- CURLOPT_CRLF: Définissez cette option à une valeur différente de 0 si vous voulez convertir les nouvelles lignes Unix en nouvelles lignes CRLF pour les transferts.

- CURLOPT_PROXYPORT: Passez un entier long comme valeur représentant le numéro du port du proxy à utiliser pour la connexion. Ce numéro de port peut également être défini dans l'option CURLOPT_PROXY.

- CURLOPT_UNRESTRICTED_AUTH: Définissez cette option à une valeur différente de 0 pour garder l'envoi du nom de l'utilisateur ainsi que le mot de passe lorsque l'on suit les chemins (en utilisant CURLOPT_FOLLOWLOCATION), même si le nom d'hôte change.

- CURLOPT_FTP_USE_EPRT: Définissez cette option à une valeur différente de 0 pour utiliser EPRT (et LPRT) lors de l'activation des téléchargements FTP. Utilisez 0 pour désactiver EPRT et LPRT et ainsi, n'utiliser que PORT.

- CURLOPT_HTTPAUTH: Passez un entier long comme valeur qui définie la méthode d'identification HTTP désirée. Ces options sont : CURLAUTH_BASIC, CURLAUTH_DIGEST, CURLAUTH_GSSNEGOTIATE, CURLAUTH_NTLM, CURLAUTH_ANY et CURLAUTH_ANYSAFE.

  Vous pouvez utiliser le séparateur | ou un opérateur pour combiner plus d'une méthode. Si vous faîtes celà, CURL interrogera le serveur pour voir quelles sont les méthodes supportées et prendra la meilleur. CURLAUTH_ANY et un alias pour CURLAUTH_BASIC | CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM et CURLAUTH_ANYSAFE est un alias pour CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM.

value doit être une chaîne de caractères pour les valeurs suivantes de option

- CURLOPT_URL : L'URL que PHP va récupérer. Vous pouvez aussi choisir cette valeur lors de l'appel à curl_init().

- CURLOPT_USERPWD : Passez une chaîne de caractères au format [nom]:[mot de passe], pour que PHP l'utilise lors de la connexion.

- CURLOPT_PROXYUSERPWD : Passez une chaîne de caractères au format [nom]:[mot de passe ], pour que PHP l'utilise lors de la connexion à un proxy HTTP.

- CURLOPT_RANGE : Passez une chaîne de caractères qui représente la plage de valeurs que vous désirez. Elle est au format "X-Y", où les valeurs de X ou Y peuvent être omises. Le transfert HTTP supporte aussi plusieurs intervalles, séparés par des virgules : X-Y,N-M.

- CURLOPT_POSTFIELDS : Passez une chaîne de caractères qui contient toutes les données à passer lors d'une opération de HTTP POST.

- CURLOPT_REFERER : Passez une chaîne de caractères qui contient l'en-tête de "REFERER", utilisé lors d'une requête HTTP.

- CURLOPT_USERAGENT : Passez une chaîne de caractères qui contient l'en-tête "user-agent" utilisé dans une requête HTTP.

- CURLOPT_FTPPORT : Passez une chaîne de caractères qui désignera l'adresse IP utilisée pour l'instruction FTP "PORT". L'instruction POST indique au serveur distant de se connecter à cette adresse IP. La chaîne peut être une adresse IP, un nom d'hôte, un nom d'interface réseau (sous UNIX), ou juste '-', pour utiliser les IP par défaut du système.

- CURLOPT_COOKIE : Passez une chaîne de caractères qui contiendra le contenu du cookie, à transmettre dans l'en-tête HTTP.

- CURLOPT_SSLCERT : Passez une chaîne de caractères qui contiendra le nom de fichier du certificat, au format PEM.

- CURLOPT_SSLCERTPASSWD : Passez une chaîne de caractères qui contient le mot de passe nécessaire pour utiliser le certificat `CURLOPT_SSLCERT`.

- CURLOPT_COOKIEFILE : Passez une chaîne de caractères qui contiendra le nom du fichier contenant les données de cookie. Le fichier de cookie peut être au format Netscape, ou simplement des en-têtes HTTP écrits dans un fichier.

- CURLOPT_CUSTOMREQUEST : Passez une chaîne de caractères qui sera utilisée à la place de GET ou HEAD lors des requêtes HTTP. Cette commande est pratique pour effectuer un DELETE ou une autre commande HTTP exotique. Les valeurs valides sont GET, POST, et plus ; i.e. n'entrez pas une requête HTTP ici. Pour le moment, entrez 'GET /index.html HTTP/1.0\r\n\r\n' serait incorrect.

  > Note : N'utilisez pas cette commande sans vous assurer que le serveur l'accepte.

- CURLOPT_PROXY: Donnez le nom du proxy HTTP au tunnel qui le demande.

- CURLOPT_INTERFACE: Passez le nom de l'interface à utiliser. Celà peut être le nom d'une interface, une adresse IP ou encore le nom de l'hôte.

- CURLOPT_KRB4LEVEL: Passez le degré de sécurité KRB4 (Kerberos 4). Chacune des valeurs (dans l'ordre du plus petit au plus grand) suivantes sont valides : 'clear', 'safe', 'confidential', 'private'. Si la chaîne passée ne correspond pas à une de ces valeurs, la valeur 'private' sera définie. Positionner cette valeur à NULL revient à désactiver la sécurité KRB4. Actuellement, la sécurité KRB4 se fonctionne uniquement avec les transaction FTP.

- CURLOPT_HTTPHEADER: Passez un tableau d'en-têtes HTTP à positionner.

- CURLOPT_QUOTE: Passez un tableau de commandes FTP à passer au serveur pour les requêtes FTP.

- CURLOPT_POSTQUOTE: Passez un tableau de commandes FTP à exécuter sur le serveur, après que les requêtes FTP ne soient effectuées.

- CURLOPT_RANDOM_FILE: Passez une chaîne qui contient un nom de fichier à utiliser pour interroger le générateur de nombre aléatoire.

- CURLOPT_EGBSOCKET: Comme CURLOPT_RANDOM_FILE excepté que vous passez une chaîne qui contient un nom de fichier vers le socket Entropy Gathering Daemon.

- CURLOPT_CAPATH: Passez une chaîne qui contient un dossier qui contient les certificats CA. Utilisez cette option avec l'option CURLOPT_SSL_VERIFYPEER.

- CURLOPT_COOKIEJAR: Passez une chaîne qui contient un nom de fichier pour y sauvegarder tous les cookies internes lorsque la connexion se ferme.

- CURLOPT_SSL_CIPHER_LIST: Passez une chaîne qui contient une liste de ciphers à utiliser avec SSL. Par exemple, RC4-SHA and TLSv1 sont des listes valides de cipher.

- CURLOPT_SSLKEY: Passez une chaîne qui contient un nom de fichier contenant votre clé privée SSL.

- CURLOPT_SSLKEYTYPE: Passez une chaîne qui contient le type de votre clé SSL privée. Les types de clés supportés sont "PEM" (default), "DER", et "ENG".

- CURLOPT_SSLKEYPASSWD: Passez une chaîne qui contient le mot de passe secret utiliser par votre clé SSL privée.

  > Note : Du fait que cette option contient un mot de passe sensible, souvenez vous de conserver le script PHP qui le contient en toute sécurité.

- CURLOPT_SSLENGINE: Passez une chaîne qui contient l'identifiant pour le moteur de cryptage de votre clé privée.

- CURLOPT_SSLENGINE_DEFAULT: Passez une chaîne qui contient l'identifiant pour le moteur de cryptage utilisé pour les opérations de cryptage asymétrique.

- CURLOPT_SSLCERTTYPE: Passez une chaîne qui contient le format de votre certificat. Les formats supportés sont "PEM" (default), "DER", et "ENG". Ceci a été ajouté à CURL 7.9.3.

- CURLOPT_ENCODING: Passez une chaîne qui définie le contenu des en-têtes Accept-Encoding: et active le décodage de la réponse. Les encodages supportés sont "identity", "deflate" et "gzip". Si une chaîne vide "" est utilisé, une en-tête contenant tous les types d'encodage supportés est envoyée.

- CURLOPT_HTTP200ALIASES: Passez un tableau de chaînes qui seront traitées comme réponses valides HTTP 200. Ceci a été ajouté en CURL 7.10.3.

Les options suivantes requièrent un pointeur de fichier, qui est obtenu avec la fonction fopen() :

- CURLOPT_FILE : Le fichier de sortie de votre transfert. Par défaut, STDOUT.

- CURLOPT_INFILE : Le fichier d'entrée de votre transfert.

- CURLOPT_WRITEHEADER : Le fichier de destination de l'en-tête de la sortie du transfert.

- CURLOPT_STDERR : Le fichier d'erreurs.

Les options suivantes attendent une chaîne qui représente le nom d'une fonction de callback :

- CURLOPT_WRITEFUNCTION: Passez le nom d'une fonction de callback où la fonction de callback prend deux paramètres. Le premier est la ressource CURL et le second, une chaîne contenant les données à écrire. En utilisant cette fonction de callback, il devient de votre responsabilité d'écrire les données. Retourne le nombre d'octets écris.

- CURLOPT_READFUNCTION: Passez le nom d'une fonction de callback où la fonction de callback prend deux paramètres. Le premier est la ressource CURL et le second, une chaîne contenant les données à lire. En utilisant cette fonction de callback, il devient de votre responsabilité de lire les données. Retourne le nombre d'octets lus. Retourne 0 à un signal EOF.

- CURLOPT_PASSWDFUNCTION: Passez le nom d'une fonction de callback où la fonction de callback prend trois paramètres. Le premier est la ressource CURL, le second, une chaîne contenant un mot de passe de prompt et le troisième, est la longueur maximale du mot de passe. Retourne une chaîne contenant le mot de passe.

- CURLOPT_HEADERFUNCTION: Passez le nom d'une fonction de callback où la fonction de callback prend deux paramètres. Le premier est la ressource CURL, le seond, une chaîne contenant les données de l'en-tête à écrire. En utilisant cette fonction de callback, il en devient de votre responsabilité de l'écriture des données de l'en-tête. Retourne le nombre d'octets écris.

Exemple 1. Initialisation d'une nouvelle session CURL et recherche d'une page Web

`<?php // Création d'une ressource CURL $ch = curl_init(); // Définition de l'URL et autres options appropriées curl_setopt($ch, CURLOPT_URL, "http://www.example.com/"); curl_setopt($ch, CURLOPT_HEADER, 0); // Récupération de l'URL et passage au navigateur curl_exec($ch); // Fermeture de la ressource CURL et libération des ressources systèmes curl_close($ch); ?>`

Précédent | Sommaire | Suivant
curl_multi_select | Niveau supérieur | curl_version