curl_setopt

Beschreibung

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

Die Funktion curl_setopt() setzt Optionen für eine cURL-Session, die durch den ch Parameter identifiziert ist. Der option Parameter stellt die Option dar, die mit dem Wert des Parameters value besetzt werden soll.

Der Wert value sollte für folgende Optionen (angegeben in dem option Parameter) vom Typ long sein:

• CURLOPT_INFILESIZE: Wenn eine Datei hochgeladen wird, sollte diese Option genutzt werden, um PHP mitzuteilen welche erwartete Größe das Infile hat.

• CURLOPT_VERBOSE: Bei Setzen dieser Option auf einen Wert ungleich ungleich 0 (Null) wird cURL eine sehr detailierte Ausgabe vornehmen.

• CURLOPT_HEADER: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird cURL den Header in die Ausgabe aufnehmen.

• CURLOPT_NOPROGRESS: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird PHP angewiesen kein cURL progress-meter für cURL Transfers anzuzeigen.

  Anmerkung: PHP setzt die Option automatisch auf einen Wert ungleich 0 (Null). Dies sollte ausschließlich für die Fehlersuche geändert werden.

• CURLOPT_NOBODY: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird der Body nicht in die Ausgabe aufgenommen.

• CURLOPT_FAILONERROR: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird PHP angewiesen bei misslungenen Aktionen (wenn der HTTP-Code größer ist als 300), ohne Fehlermeldung weiter zu arbeiten. Dieses Verhalten ist voreingestellt.

• CURLOPT_UPLOAD: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird PHP auf ein Upload vorbereitet.

• CURLOPT_POST: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird PHP angewiesen die reguläre HTTP POST Methode zu nutzen. Dieses ist ein application/x-www-form-urlencoded, was meist von HTML Formularen genutzt wird.

• CURLOPT_FTPLISTONLY: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird PHP nur die Namen der FTP Verzeichnisse auflisten.

• CURLOPT_FTPAPPEND: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird PHP angewiesen die Übertragung der Datei fortzusetzen, anstatt jene zu überschreiben.

• CURLOPT_NETRC: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird PHP die lokale Datei ~./netrc absuchen, um den Benutzternamen und das Passwort zu finden mit dem die Autorisierung geschehen soll.

• CURLOPT_FOLLOWLOCATION: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird jedem "Location: " (Ein Feld des HTTP-Headers) gefolgt. Zu beachten ist, dass dies rekursiv geschieht.

• CURLOPT_PUT: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird ein HTTP PUT einer Datei durchgeführt. Diese Datei muss mit CURLOPT_INFILE gesetzt und mit CURLOPT_INFILESIZE näher beschrieben werden.

• CURLOPT_MUTE: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) wird PHP keine Ausgabe bezüglich der cURL Funktionen machen.

• CURLOPT_TIMEOUT: Ein Wert vom Typ long wird als Parameter übergeben und gibt die Zeit in Sekunden an, die die cURL-Funktionen haben, um die gewünschten Aktionen durchzuführen.

• CURLOPT_LOW_SPEED_LIMIT: Ein Wert vom Typ long wird als Parameter übergeben. Er gibt die Transfergeschwindigkeit in Bytes pro Sekunde an, die bei Unterschreitung in Kombination mit der Überschreitung von CURLOPT_LOW_SPEED_TIME Sekunden bewirkt, dass der Transfer aufgrund der zu niedrigen Transferrate abgebrochen wird.

• CURLOPT_LOW_SPEED_TIME: Ein Wert vom Typ long wird als Parameter übergeben und gibt die Zeit in Sekunden an, in der die Transferrate unter CURLOPT_LOW_SPEED_LIMIT gedultet wird. Nach dieser Zeit wird die Transferrate als zu langsam angesehen und der Transfer wird beendet.

• CURLOPT_RESUME_FROM: Ein Wert vom Typ long wird als Parameter erwartet und gibt den Offset in Bytes an, an dem der Transfer forgesetzt werden soll.

• CURLOPT_CAINFO: Als Parameter wird ein Dateiname erwartet, die ein oder mehrere Zertifikate enthält, mit dem am Peer verfiziert werden kann. Die Nutzung dieser Option macht nur in Kombination mit CURLOPT_SSL_VERIFYPEER Sinn.

• CURLOPT_SSL_VERIFYPEER: Ein Wert vom Typ long wird als Parameter übergeben. Ist dieser gleich 0 (Null) stellt cURL die Überprüfung des Peerzertifikats ein. (Ab cURL 7.10 ist die Voreinstellung für diese Option TRUE.) Alternative Zertifikate zur Überprüfung können mit der CURLOPT_CAINFO Option angegeben werden (hinzugefiügt in cURL 7.9.8) oder ein Zertifikat-Verzeichniss kann mit CURLOPT_CAPATH ausgewiesen werden. Ab cURL 7.10, installiert cURL ein vorgegebenes default Packet. CURLOPT_SSL_VERIFYHOST muss ggf. auf 1 oder 0 gesetzt werden, falls CURLOPT_SSL_VERIFYPEER deaktiviert (also auf 2 gesetzt) ist.

• CURLOPT_SSLVERSION: Ein Wert vom Typ long wird als Parameter erwartet und gibt die SSL Version (2 oder 3) an die genutzt werden soll. PHP wird selber versuchen eine herauszusuchen, trotzdem erfordern einige Situationen das manuelle Setzen dieser Option.

• CURLOPT_SSL_VERIFYHOST: Setzen Sie einen Wert vom Typ long falls cURL den Namen des Peer Zertifikates beim SSL Handshake überprüfen sollte. Der Wert 1deutet an, dass nach der Existenz des Namens gesehen werden soll, der Wert 2 deutet an, dass sichergestellt werden soll, dass eine Übereinstimmung mit dem angegebenen Hostnamen vorliegt.

• CURLOPT_TIMECONDITION: Ein Wert vom Typ long wird erwartet und gibt an wie CURLOPT_TIMEVALUE behandelt werden soll. Diser Wert kann auf TIMECOND_IFMODSINCE oder TIMECOND_ISUNMODSINCE gesetzt werden. Dies ist nur eine Besonderheit des HTTPs'.

• CURLOPT_TIMEVALUE: Ein Wert vom Typ long wird erwartet und gibt die Zeit in Sekunden seit dem 1. Januar 1970 an. Die Zeit wird wie mit Hilfe von CURLOPT_TIMEVALUE definiert, oder es wird wie per Voreinstellung TIMECOND_IFMODSINCE, genutzt.

• CURLOPT_RETURNTRANSFER: Bei Setzen dieser Option auf einen Wert ungleich 0 (Null) gibt cURL den Transfer zurück, anstatt die Ausgabe vorzunehmen.

Der value Parameter sollte für folgende option Parameter ein String sein:

• CURLOPT_URL: Dies ist die URL, die PHP abrufen soll. Beim Initialisieren eine Session mit curl_init() kann diese Option ebenfalls gesetzt werden.

• CURLOPT_USERPWD: Erwartet wird ein String in dem Format [Benutzername]:[Passwort], den PHP für die Verbindung nutzt.

• CURLOPT_PROXYUSERPWD: Erwartet einen String in dem Format [Benutztername]:[Passwort] für die Verbindung mit einem HTTP-Proxy.

• CURLOPT_RANGE: Übergeben wird das gewünschte Intervall. Es sollte in dem Format "X-Y" sein, wobei X oder Y ausgelassen werden sollen. Transfers über das HTTP unterstützen ebenfalls Intervalle, die mit Kommas getrennt werden (X-Y,N-M).

• CURLOPT_POSTFIELDS: Übergeben wird ein String, der die gesamten Daten enhält, die in einer HTTP POST Aktion gesendet werden sollen.

• CURLOPT_REFERER: Übergeben wird ein String, der den Wert des Referer-Feldes im HTTP Header enthält und in einer HTTP Anfrage genutzt werden soll.

• CURLOPT_USERAGENT: Übergeben wird ein String, der den Wert des User-Agent-Feldes im HTTP Header enthält und in einer HTTP Anfrage genutzt werden soll.

• CURLOPT_FTPPORT: Übergeben wird ein String, der genutzt wird, um die IP-Adresse zu erlangen, die von der FTP POST Answeisung genutzt wird. Die POST Anweisung teilt dem entfernten Server mit, zu der angegebenen IP-Adresse zu verbinden . Der String kann eine einfache IP-Addresse, ein Hostname, der Name eines Netzwerkinterfaces (unter Unix), oder nur '-' sein, um die vordefinierte IP-Addresse (des Systems) zu nutzen.

• CURLOPT_COOKIE: Übergeben wird ein String, der den Inhalt des Cookies enthält, der in dem HTTP-Header gesetzt werden soll.

• CURLOPT_SSLCERT: Übergeben wird ein String, der den Namen der Datei enhält, die das PEM formatierte Zertifikat enthält.

• CURLOPT_SSLCERTPASSWD: Übergeben wird ein String, der das Passwort enthält welches erforderlich ist, um das CURLOPT_SSLCERTM Zertifikat zu nutzen.

• CURLOPT_COOKIEFILE: Übergeben wird ein String, der den Namen der Datei enhält, die die Cookiedaten enthält. Diese Datei kann im Netscape Format sein, oder HTTP geformte Header in einer einfachen Textdatei.

• CURLOPT_CUSTOMREQUEST: Übergeben wird ein String, der als Kommando an Stelle von GET oder HEAD bei einer HTTP-Anfrage genutzt werden soll. Dies ist nützlich wenn z.B. ein DELETE oder andere weniger übliche Anfragen ausgeführt werden sollen. Gültige Werte sind z.B. GET, POST usw. Vollständige HTTP-Anfragen, wie 'GET /index.html HTTP/1.0\r\n\r\n' sind ungültig.

  Anmerkung: Führen Sie diese Anfragen nicht durch ohne sicherzugehen, dass Ihr Server die betreffenden Kommandos unterstützt.

• CURLOPT_PROXY: Übergeben wird ein String, der den Namen des HTTP-Proxies angibt über den die Anfragen geleitet werden sollen.

• CURLOPT_INTERFACE: Übergeben wird ein String, der den Namen des zu nutzenden Netzwerkinterfaces für ausgehende Daten enthält. Neben dem Namen des Interfaces, kann auch eine IP-Adresse oder ein Hostname übergeben werden.

• CURLOPT_KRB4LEVEL: Übergeben Sie die KRB4 (Kerberos 4) Sicherheitsstufe. Folgende Werte (von niedriger zu höherer Stufe) sind gültig: 'clear', 'safe', 'confidential', 'private'. Sollte der String keine dieser Werte enthalten, dann wird die hóchste Stufe, d.h 'private' genutzt. Sollte diese Option mit dem Wert NULL besetzt werden, wird KRB4 Security deaktiviert. Bislang wird KRB4 nur unter Verwendung des FTP unterstützt.

• CURLOPT_HTTPHEADER: Übergeben wird ein Array mit HTTP-Header, die gesetzt werden sollen.

• CURLOPT_QUOTE: Übergeben wird ein Array mit FTP-Kommandos, die vor der FTP Anfrage auf dem Server ausgeführt werden sollen.

• CURLOPT_POSTQUOTE: Übergeben wird ein Array FTP-Kommandos, die nach der FTP Anfrage auf dem Server ausgeführt werden sollen.

Die folgenden Optionen erwarten einen Dateizeiger, der mit Hilfe von fopen() erstellt werden kann:

• CURLOPT_FILE: Die Datei, in die die Ausgabe des Transfers geschrieben werdem soll. Voreingestellt ist STDOUT.

• CURLOPT_INFILE: Die Datei aus der die Daten des Transfers stammt.

• CURLOPT_WRITEHEADER: Die Datei in die die Header-Teile der Ausgabe geschrieben werden sollen.

• CURLOPT_STDERR: Die Datei, in die die aufgetretenen Fehler geschrieben werden sollen anstatt nach STRDERR.

Beispiel 1. Initialisierung einer neunen cURL-Session und das abrufen einer Webseite <?php    // erzeuge einen neuen cURL-Handle    $ch = curl_init();         // setze die URL und andere Optionen    curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");    curl_setopt($ch, CURLOPT_HEADER, 0);         // führe die Aktion aus und gebe die Daten an den Browser weiter    curl_exec($ch);         // schließe den cURL-Handle und gebe die Systemresourcen frei    curl_close($ch); ?>