Funkcje bilbioteki cURL w PHP

Poniżej znajduje się lista dostępnych funkcji biblioteki cURL w PHP razem z opisami i przykładami użycia.

Całą tabelkę poniżej można przeciągać jak i resztę tabel także, wystarczy kliknąć i przytrzymać przycisk myszy.

Nazwa funkcjiOpis funkcjiPrzykładowe użycie
curl_initInicjuje sesję i zwraca uchwyt dla reszty funkcji. Przybiera jeden opcjonalny argument tj. adres URL, adres można zamiast tutaj podać w opcji “CURLOPT_URL”.
$ch = curl_init('https://tosiek.pl/');
curl_setoptUstawia pojedynczą opcję dla zwykłej sesji cURL.
curl_setopt($ch, CURLOPT_URL, "https://tosiek.pl/");
curl_setopt_arrayUstawia kilka opcji dla sesji curla na raz przy pomocy tablicy gdzie klucz to opcja a wartość to ustawienie dla tej opcji.
$options = array(
	CURLOPT_URL => 'https://tosiek.pl/',
	CURLOPT_HEADER => false,
);
curl_setopt_array($ch, $options);
curl_execWywołuje sesję curl_init z podanymi wcześniej parametrami, zwraca TRUE przy powodzeniu i FALSE przy nieudanym wywołaniu. Jeśli “CURLOPT_RETURNTRANSFER” zostanie ustawione na TRUE to ta funkcja zwróci zawartość strony przy udanym wywołaniu lub FALSE przy nieudanym.
$result = curl_exec($ch);
curl_getinfoPobiera informacje o wykonanej sesji cURL i zwraca je w postaci tablicy.
$curl_info = curl_getinfo($ch);
$curl_info = array(
	'url' => 'https://tosiek.pl/',
	'content_type' => 'text/html; charset=utf-8',
	'http_code' => 200,
	'header_size' => 862,
	'request_size' => 52,
	'filetime' => -1,
	'ssl_verify_result' => 0,
	'redirect_count' => 0,
	'total_time' => 0.344,
	'namelookup_time' => 0.047,
	'connect_time' => 0.172,
	'pretransfer_time' => 0.172,
	'size_upload' => 0,
	'size_download' => 80,
	'speed_download' => 232,
	'speed_upload' => 0,
	'download_content_length' => -1,
	'upload_content_length' => 0,
	'starttransfer_time' => 0.344,
	'redirect_time' => 0,
	'certinfo' => array(),
);
curl_errnoZwraca numer ostatniego błędu lub 0 (zero) w przypadku braku błędów.
$curl_error_number = curl_errno($ch);
curl_errorZwraca opis i wiadomość dotyczącą ostatniego błędu. W celu upewnienia się, że błąd wystąpił użyj funkcji curl_errno, która zwraca 0 (zero) jeśli wszystko jest w porządku a po napotkaniu błędu, jego numer lub curl_exec z kolei ta zwraca FALSE przy błędzie.
$curl_error_message = curl_error($ch);
curl_copy_handleKopiuje parametry danej sesji i zwraca w postaci nowego uchywtu sesji.
$ch2 = curl_copy_handle($ch);
curl_closeZamyka pojedynczą sesję cURL i zwalnia użyte zasoby (pamięć etc.). Usuwa takze uchwyt cURL $ch.
curl_close($ch);
curl_multi_initInicjuje multi-sesję i zwraca uchwyt dla niej, nie przyjmuje żadnych argumentów.
$mh = curl_multi_init();
curl_multi_add_handleDodaje zwykłą pojedynczą sesję cURL do jednej multi-sesji którą trzeba uprzednio utworzyć.
curl_multi_add_handle($mh, $ch);
curl_multi_execWywołuje i aktywuje multi-sesje, pierwszy parametr uchwyt multi-sesji stworzony za pomocą curl_multi_init a drugi informacja o tym czy jest aktywna ta multi-sesja.
$mrc = curl_multi_exec($mh, $active);
do {
	$mrc = curl_multi_exec($mh, $active);
} while ($mrc == CURLM_CALL_MULTI_PERFORM);
 
while ($active && $mrc == CURLM_OK) {
	if (curl_multi_select($mh) != -1) {
		do {
			$mrc = curl_multi_exec($mh, $active);
		} while ($mrc == CURLM_CALL_MULTI_PERFORM);
	}
}
curl_multi_selectCzeka aż wszystkie dane zostaną zwrócone przy wszystkich połączeniach multi-sesji lub aż upłynie czas timeout; zwraca -1 przy błędach. Przyjmuje dwa parametry, uchwyt multi-sesji oraz czas timeout.
$ready = curl_multi_select($mh, '15.0');
curl_multi_info_readZwraca informacje o multi-sesji w tablicy z trzema kluczami; “msg” zwraca zawsze: ‘CURLMSG_DONE’, “result” zwraca jeden wynik spośród: ‘CURLE_*’; w przypadku powodzenia zwraca: ‘CURLE_OK’, “handle” zwraca uchwyt sesji cURL, której to informacje dotyczą. Powtórne wywołanie funkcji zwróci kolejne inne wyniki. Przyjmuje dwie wartości, pierwsza to uchwyt multi-sesji a druga to zmienna przechowująca ilość wiadomości w kolejce.
$curl_multi_info = curl_multi_info_read($mh);
		$curl_multi_info = array(
	'msg' => CURLMSG_DONE,
	'result' => CURLE_OK,
	'handle' => resource(2, curl),
);
curl_multi_getcontentJeżeli “CURLOPT_RETURNTRANSFER” jest ustawione na TRUE to zwraca zawartość strony, jedyny argument to zwykła sesja pojedynczego – uchwyt cURL.
$content = curl_multi_getcontent($ch);
curl_multi_remove_handleUsuwa sesję pojedynczego cURL z multi-sesji i umożliwia wykonanie curl_exec na zwolnionym uchwycie, po tym należy zamknąć multi-sesję oraz pojedyncze sesje żeby zwolnić użyte zasoby.
curl_multi_remove_handle($mh, $ch1);
curl_multi_closeKończy multi-sesję, nadal jednak należy usunąć zwykłe sesje z multi-sesji za pomocą curl_multi_remove_handle oraz zakończyć każdą zwykłą pojedynczą sesje cURL aby zwolnić zasoby.
curl_multi_close($mh);
curl_versionZwraca informacje o cURL w postaci tablicy.
$version = curl_version();

Wartości jakie przyjmują funkcje razem z legendą oznaczeń:

  • B – boolean, TRUE lub FALSE
  • I – wartości liczbowe
  • S – ciągi znaków
  • A – tablice
  • SR – stream resource; uchwyty do plików w wypadku curla

Nagłówki HTTP

Wszystkie opcje dotyczące nagłówków HTTP oraz typów zapytań POST, GET oraz HEAD jak i PUT.

Nazwa opcjiDomyślna wartość oraz typ wartości jakie przyjmujeOpis
CURLOPT_AUTOREFERERtrue (B)wysyła nagłówek “Referer:” po napotkaniu przekierownaia i podążaniu za nagłówkiem “Location:”
CURLOPT_CRLFtrue (B)true jeśli ma konwertować unixowe końce linii “\n”(LF) na “\r\n”(CRLF) w nagłówkach, transferach itp.
CURLOPT_FOLLOWLOCATIONfalse (B)podążaj za przekierowaniami i adresami w nagłówku “Location:”; uważaj bo moze to być nieskończona liczba przekeirowań jeśli “CURLOPT_MAXREDIRS” nie zostanie ustawione
CURLOPT_HEADERfalse (B)umieszcza nagłówki HTTP zwrotne w wynikowych danych curla
CURLINFO_HEADER_OUTfalse (B)nie jestem pewien ale chyba zwraca nagłówki HTTP przy wywołaniu curl_getinfo(); lub “śledzi uchwyt ciągu zapytania”?
CURLOPT_HTTPGETtrue (B)true aby zresetować zapytanie do metody GET; wymagane tylko jeśli ta opcja została wcześniej zmieniona bo jest to ustawione domyślnie
CURLOPT_NOBODYfalse (B)true aby wykluczyć główną część dokumentu (tj. body, to co po nagłówkami HTTP). Metoda zapytanai zmienai się na “HEAD”. Ustawienei tego na false nie mzienai metody zapytania na GET -> patrz “CURLOPT_HTTPGET”
CURLOPT_POSTfalse (B)ustaw na true aby wykonać regularne / zwykłe zapytnaie post i ustawic typ kodownaia danych na najbardziej popularny tj. “application/x-www-form-urlencoded”
CURLOPT_PUTfalse (B)true aby wykonać polecenie PUT dla pliku poprzez HTTP; plik do wysłanai musi posiadac dwie opcje: “CURLOPT_INFILE” oraz “CURLOPT_INFILESIZE”
CURLOPT_CUSTOMREQUEST” (S)Niestandardowe zapytnaie HTTP do użycia zamaist zapytań ‘GET’ oraz ‘HEAD’. Jest to użyteczne gdy chcemy wykonać np. zapytanie ‘DELETE’ lub inne bardziej skomplikowane zapytania HTTP. Prawidłowymi wartościami są np. ‘GET’, ‘POST’, ‘CONNECT’ i tak dalej, nie należy wprowadzać całej linijki żądania. Przykładowo podanie ‘GET /index.html HTTP/1.0\r\n\r\n’ będzie błędem.

Nie używaj tej opcji zanim nie upewnisz się czy serwer obsługuje dane zapytanie.

CURLOPT_ENCODING” (S)Zawartość nagłówka HTTP “Accept-Encoding:”. Włącza to dekodowanie odpowiedzi serwera. Wspierane kodowania to: ‘identity’, ‘deflate’ oraz ‘gzip’ np. ‘gzip, deflate’. Jeśli wartość jest pusta ” to wysyłany jest nagłówek zawierajace wszystkei obsługiwane typy.
CURLOPT_POSTFIELDS” (S/A)Pełne dane zapytania HTTP “POST”. Aby wysłać plik metodą POST należy poprzedzić jego pełną ścieżkę znakiem ‘@’ (ważne należy użyć bezwzględnej, pełnej ścieżki). Typ mime pliku można określić za pomocą parametru ‘type’ np. ‘@/home/file.txt; type=text/plain;’. Wartością dla tej opcji może być łanćuch składjący sie z kolejnych parametrów i ich wartości zakodowanych za pomocą urlencode() w postaci: ‘parametr1=wartosc1&parametr2=wartosc2&…’ można takze przekazać dane dla tej opcji w postaci tablicy przy czym klucz w tablicy to nazwa parametru a wartość to wartość tegożż parametru. Jeśli wartością dla tej opcji jest tablica nagłówek “Content-Type:” zostanie ustawiony i wysłany jako: “multipart/form-data”.

Od wersji PHP 5.2.0 aby plik parsowany z prefixem w postaci ‘@’ został prawidłowo wysłany i zinterpretowany dane muszą być dostarczone w postaci tablicy.

CURLOPT_REFERER” (S)Zawartość nagłówka HTTP “Referer:” używanego przy zapytaniach.
CURLOPT_USERAGENT” (S)Zawartość nagłówka HTTP “User-Agent:” używanego przy zapytaniu.
CURLOPT_HTTPHEADERarray(‘Content-type: text/plain’, ‘Content-length: 0’) (A)Tablica z nagłówkami HTTP do wysłania przy wykonywaniu zapytania.