XII. cURL, Client URL Bibiothek-Funktionen

Einführung

PHP unterstützt libcurl, eine Bibiothek entwickelt von Daniel Stenberg, die es erlaubt sich mit Servern zu verbinden und über diverse Protokolle zu kommunizieren. Libcurl unterstützt zur Zeit folgende Protokolle: http, https, ftp, gopher, telnet, dict, file und ldap. Libcurl unterstützt des weiteren HTTPS Zertifikate, HTTP POST, HTTP PUT, und das hochladen von Dateien unter Benutzung des FTP Protokolls (ist auch unter Nuztung der FTP Erweiterung PHPs' möglich), HTTP Fomular basierende Uploads, Proxies, Cookies, und Benutzer/Password Authentifikation.

Diese Funktionen wurden in PHP 4.0.2 hinzugefügt.

Anforderungen

Um cURL Functionen nutzen zu können, muss man das cURL Packet installieren. PHP fordert cURL 7.0.2-beta oder neuer. PHP wird nicht mir einer Version älter als 7.0.2-beta laufen In PHP 4.2.3, wird cURL in der Version 7.9.0 oder höher vorausgesetzt. Bei PHP 4.3.0, wird die cURL Version 7.9.8 oder höher gebraucht. PHP 5.0.0 wird wahrscheinlich eine cURL Version neuer als 7.10.5 voraussetzen.

Installation

Um PHP mit cURL-Unterstützung nutzen zu können, muss man PHP mit der Option --with-curl[=DIR] kompilieren, wobei DIR das Verzeichnis angibt in dem sich die Bibiotheken und die Includedateien befinden. In dem "include" Verzeichnis sollte ein Unterverzeichnis mit dem Titel "curl" existieren, dass die Dateien easy.h und curl.h enthält . Zudem sollte eine Datei namens libcurl.a in dem "lib"-Verzeichnis sein. Ab PHP 4.3.0 kann man PHP mit der Option --with-curlwrappers konfigurieren, um cURL für URL-Streams nuzten zu können.

Anmerkung für Win32-Nutzer: Um dieses Modul in einer Windows-Umgebung nutzen zu können, müssen libeay32.dll und ssleay32.dll aus dem DLL-Verzeichnis des PHP/Win32 binary Packets in das SYSTEM32-Verzeichnis des Windows PC's kopiert werden. (z.B.: C:\WINNT\SYSTEM32 oder C:\WINDOWS\SYSTEM)

Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und sind nur definiert, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

CURLOPT_PORT (integer)
CURLOPT_FILE (integer)
CURLOPT_INFILE (integer)
CURLOPT_INFILESIZE (integer)
CURLOPT_URL (integer)
CURLOPT_PROXY (integer)
CURLOPT_VERBOSE (integer)
CURLOPT_HEADER (integer)
CURLOPT_HTTPHEADER (integer)
CURLOPT_NOPROGRESS (integer)
CURLOPT_NOBODY (integer)
CURLOPT_FAILONERROR (integer)
CURLOPT_UPLOAD (integer)
CURLOPT_POST (integer)
CURLOPT_FTPLISTONLY (integer)
CURLOPT_FTPAPPEND (integer)
CURLOPT_NETRC (integer)
CURLOPT_FOLLOWLOCATION (integer)
CURLOPT_FTPASCII (integer)
CURLOPT_PUT (integer)
CURLOPT_MUTE (integer)
CURLOPT_USERPWD (integer)
CURLOPT_PROXYUSERPWD (integer)
CURLOPT_RANGE (integer)
CURLOPT_TIMEOUT (integer)
CURLOPT_POSTFIELDS (integer)
CURLOPT_REFERER (integer)
CURLOPT_USERAGENT (integer)
CURLOPT_FTPPORT (integer)
CURLOPT_LOW_SPEED_LIMIT (integer)
CURLOPT_LOW_SPEED_TIME (integer)
CURLOPT_RESUME_FROM (integer)
CURLOPT_COOKIE (integer)
CURLOPT_SSLCERT (integer)
CURLOPT_SSLCERTPASSWD (integer)
CURLOPT_WRITEHEADER (integer)
CURLOPT_SSL_VERIFYHOST (integer)
CURLOPT_COOKIEFILE (integer)
CURLOPT_SSLVERSION (integer)
CURLOPT_TIMECONDITION (integer)
CURLOPT_TIMEVALUE (integer)
CURLOPT_CUSTOMREQUEST (integer)
CURLOPT_STDERR (integer)
CURLOPT_TRANSFERTEXT (integer)
CURLOPT_RETURNTRANSFER (integer)
CURLOPT_QUOTE (integer)
CURLOPT_POSTQUOTE (integer)
CURLOPT_INTERFACE (integer)
CURLOPT_KRB4LEVEL (integer)
CURLOPT_HTTPPROXYTUNNEL (integer)
CURLOPT_FILETIME (integer)
CURLOPT_WRITEFUNCTION (integer)
CURLOPT_READFUNCTION (integer)
CURLOPT_PASSWDFUNCTION (integer)
CURLOPT_HEADERFUNCTION (integer)
CURLOPT_MAXREDIRS (integer)
CURLOPT_MAXCONNECTS (integer)
CURLOPT_CLOSEPOLICY (integer)
CURLOPT_FRESH_CONNECT (integer)
CURLOPT_FORBID_REUSE (integer)
CURLOPT_RANDOM_FILE (integer)
CURLOPT_EGDSOCKET (integer)
CURLOPT_CONNECTTIMEOUT (integer)
CURLOPT_SSL_VERIFYPEER (integer)
CURLOPT_CAINFO (integer)
CURLOPT_COOKIEJAR (integer)
CURLOPT_SSL_CIPHER_LIST (integer)
CURLOPT_BINARYTRANSFER (integer)
CURLCLOSEPOLICY_LEAST_RECENTLY_USED (integer)
CURLCLOSEPOLICY_LEAST_TRAFFIC (integer)
CURLCLOSEPOLICY_SLOWEST (integer)
CURLCLOSEPOLICY_CALLBACK (integer)
CURLCLOSEPOLICY_OLDEST (integer)
CURLINFO_EFFECTIVE_URL (integer)
CURLINFO_HTTP_CODE (integer)
CURLINFO_HEADER_SIZE (integer)
CURLINFO_REQUEST_SIZE (integer)
CURLINFO_TOTAL_TIME (integer)
CURLINFO_NAMELOOKUP_TIME (integer)
CURLINFO_CONNECT_TIME (integer)
CURLINFO_PRETRANSFER_TIME (integer)
CURLINFO_SIZE_UPLOAD (integer)
CURLINFO_SIZE_DOWNLOAD (integer)
CURLINFO_SPEED_DOWNLOAD (integer)
CURLINFO_SPEED_UPLOAD (integer)
CURLINFO_FILETIME (integer)
CURLINFO_SSL_VERIFYRESULT (integer)
CURLINFO_CONTENT_LENGTH_DOWNLOAD (integer)
CURLINFO_CONTENT_LENGTH_UPLOAD (integer)
CURLE_OK (integer)
CURLE_UNSUPPORTED_PROTOCOL (integer)
CURLE_FAILED_INIT (integer)
CURLE_URL_MALFORMAT (integer)
CURLE_URL_MALFORMAT_USER (integer)
CURLE_COULDNT_RESOLVE_PROXY (integer)
CURLE_COULDNT_RESOLVE_HOST (integer)
CURLE_COULDNT_CONNECT (integer)
CURLE_FTP_WEIRD_SERVER_REPLY (integer)
CURLE_FTP_ACCESS_DENIED (integer)
CURLE_FTP_USER_PASSWORD_INCORRECT (integer)
CURLE_FTP_WEIRD_PASS_REPLY (integer)
CURLE_FTP_WEIRD_USER_REPLY (integer)
CURLE_FTP_WEIRD_PASV_REPLY (integer)
CURLE_FTP_WEIRD_227_FORMAT (integer)
CURLE_FTP_CANT_GET_HOST (integer)
CURLE_FTP_CANT_RECONNECT (integer)
CURLE_FTP_COULDNT_SET_BINARY (integer)
CURLE_PARTIAL_FILE (integer)
CURLE_FTP_COULDNT_RETR_FILE (integer)
CURLE_FTP_WRITE_ERROR (integer)
CURLE_FTP_QUOTE_ERROR (integer)
CURLE_HTTP_NOT_FOUND (integer)
CURLE_WRITE_ERROR (integer)
CURLE_MALFORMAT_USER (integer)
CURLE_FTP_COULDNT_STOR_FILE (integer)
CURLE_READ_ERROR (integer)
CURLE_OUT_OF_MEMORY (integer)
CURLE_OPERATION_TIMEOUTED (integer)
CURLE_FTP_COULDNT_SET_ASCII (integer)
CURLE_FTP_PORT_FAILED (integer)
CURLE_FTP_COULDNT_USE_REST (integer)
CURLE_FTP_COULDNT_GET_SIZE (integer)
CURLE_HTTP_RANGE_ERROR (integer)
CURLE_HTTP_POST_ERROR (integer)
CURLE_SSL_CONNECT_ERROR (integer)
CURLE_FTP_BAD_DOWNLOAD_RESUME (integer)
CURLE_FILE_COULDNT_READ_FILE (integer)
CURLE_LDAP_CANNOT_BIND (integer)
CURLE_LDAP_SEARCH_FAILED (integer)
CURLE_LIBRARY_NOT_FOUND (integer)
CURLE_FUNCTION_NOT_FOUND (integer)
CURLE_ABORTED_BY_CALLBACK (integer)
CURLE_BAD_FUNCTION_ARGUMENT (integer)
CURLE_BAD_CALLING_ORDER (integer)
CURLE_HTTP_PORT_FAILED (integer)
CURLE_BAD_PASSWORD_ENTERED (integer)
CURLE_TOO_MANY_REDIRECTS (integer)
CURLE_UNKNOWN_TELNET_OPTION (integer)
CURLE_TELNET_OPTION_SYNTAX (integer)
CURLE_OBSOLETE (integer)
CURLE_SSL_PEER_CERTIFICATE (integer)

Beispiele

Wenn PHP mit cURL-Unterstützung kompiliert und installiert ist, kann mit der Benutzung der cURL-Funktionen begonnen werden. Die Idee die hinter den Funktionen steckt, ist dass man mit Hilfe von curl_init() eine cURL-Session initialisiert, alle für den Transfer nötigen Optionen unter Verwendung von curl_setopt() setzt und dann die Session mittels curl_exec() ausführt, um dann schließlich curl_close() zur Beendigung der Session zu nutzen.

Folgendes Beispiel nutzt die cURL-Functionen, um die Homepage von example.com in eine Datei zu speichern:
Beispiel 1. Nutzung von PHP's cURL-Modul, um die Homepage von example.com herunterzuladen
<?php //Die Session initialisieren $ch = curl_init("http://www.example.com/"); $fp = fopen("example_homepage.txt", "w"); //Session Optionen setzen curl_setopt($ch, CURLOPT_FILE, $fp); curl_setopt($ch, CURLOPT_HEADER, 0); //Ausführen der Aktionen curl_exec($ch); //Session beenden curl_close($ch); fclose($fp); ?>

Inhaltsverzeichnis
curl_close -- Eine cURL-Session beenden
curl_copy_handle -- Copy a cURL handle along with all of it's preferences
curl_errno -- Gibt die letzte Fehlernummer zurück
curl_error -- Gibt eine Fehlermeldung als String zurück
curl_exec -- Eine cURL Session ausführen
curl_getinfo -- Informationen zu einem bestimmten Transfer abfragen
curl_init -- Eine cURL-Session initialisieren
curl_multi_add_handle -- Einen normalen cURL-Handle zu einem cURL Multi-handle hinzufügen
curl_multi_close -- Eine Gruppe von cURL-Handlern schließen
curl_multi_exec -- Die Unterverbindungen des cURL Handles' ausführen
curl_multi_getcontent -- Den Inhalt des cURL-Handles zurückgeben, falls CURLOPT_RETURNTRANSFER gesetzt ist
curl_multi_info_read -- Informationen über die aktuellen Transfers abfragen
curl_multi_init -- Gibt einen neuen cURL-Multi-Handle zurück
curl_multi_remove_handle -- Einen Multi-Handle von einer Handle-Gruppe entfernen
curl_multi_select -- Alle Sockets abfragen, die mit der cURL Erweiterung assoziiert sind und ausgewählt werden können
curl_setopt -- Eine Option für einen cRUL Transfer setzen
curl_version -- Gibt die aktuelle cURL-Version zurück