Библиотека CURL (Client URL Library)

Файлы и сети

🕛 01.11.2006, 13:30

PHP поддерживает библиотеку libcurl, созданную Даниелем Стенбер-гом (Daniel Stenberg), которая позволяет осуществлять подключение и взаимодействие с разными типами серверов, используя различные протоколы. В настоящее время libcurl поддерживает протоколы: http, https, ftp, gopher, telnet, diet, file, Idap. Также библиотека поддерживает сертификаты HTTPS, методы HTTP POST и PUT, загрузку с FTP и HTTP, прокси, cookies и аутентификацию пользователя с паролем.

Для того чтобы использовать функции CURL, необходимо установить пакет (package) CURL (его можно загрузить с http://curl.haxx.se/). РНР необходима версия CURL 7.0.2-beta или выше. Затем нужно перекомпилировать РНР с параметром - with-curl[=DIR], где DIR указывает на месторасположение каталога, содержащего каталоги lib и include. В каталоге include должна находиться папка curl, содержащая файлы easy.h n curl.h, а в каталоге lib должен находиться файл libcurl.a.

Схема использования функций проста: сначала инициализируется сессия CURL, используя функцию cur'MnitO, при этом устанавливаются параметры передачи, с которыми она будет выполнена функцией curl_exec(); после чего сессия может быть завершена с помощью curl_ close(). Далее приводится пример, возвращающий домашнюю страницу РНР и сохраняющий ее в файле.

<?php
$ch = curl_imt ("http://www.php.net/"):
$fp = fopen ("php_homepage.txt". "w"):
curl_setopt ($ch. CURLOPTJILE. $fp):
curl_setopt ($ch. CURLOPT_HEADER. 0).
curl_exec ($ch): curl_close ($ch):
fclose ($fp;. ?>

curl_ init

Открытие сеанса CURL

int cur!_init ([string url])

Инициализирует новую сессию и возвращает дескриптор CURL, далее используемый функциями curl_setopt(), curl_exec() и curl_close(). В функции можно указать необязательный аргумент url, в дальнейшем используемый как параметр CURLOPT_URL, который также можно установить функцией curl_setopt().

<?php
$ch = curljmt()
cjrl_setopt
($ch. CURLOPT_URL. "http://www.zend.com/"):
curl_setopt ($ch. CURLOPTJHEADER. 0):
curl_exec ($ch). curl_close ($ch);?>

См. также: curl_close(), curl_setopt().

curl_setopt

Установка параметров передачи CURL

boo! curl_setopt (int ch, string option, mixed value)

Функция устанавливает параметр, имеющий имя option сессии CURL с именем ch, в значение value.

Для следующих возможных значений аргумента option соответствующее значение value должно указываться в виде целого числа (тип long):

CURLOPT_INFILESIZE: установить ожидаемый размер получаемого файла при его загрузке на удаленный сервер;
CURLOPTJ/ERBOSE: при ненулевом значении будет сообщаться все, что происходит в ходе сессии;
CURLOPT_HEADER: при ненулевом значении заголовок будет включаться в содержимое вывода;
CURLOPT_NOPROGRESS: при ненулевом значении блокирует отображение индикатора хода выполнения (progress meter) операций передачи (CURL transfers). (По умолчанию этот параметр установлен, и его следует изменять только в целях отладки);
CURLOPT_NOBODY: при ненулевом значении содержимое «BODY» не будет включаться в вывод;
CURLOPT_FAILONERROR: при ненулевом значении будет происходить безмолвное завершение сценария РНР, в случае получения кода возврата HTTP со значением, большим чем 300. По умолчанию же происходит нормальный возврат в сценарий, с игнорированием кода, вызвавшего ошибку;
CURLOPTJJPLOAD: при ненулевом значении подготавливает РНР для загрузки;
CURLOPT_POST: при ненулевом значении указывает РНР выполнить обычный метод HTTP POST. Тип POST будет иметь нормальный для HTML-форм вид application/x-www-from-urlencoded;
CURLOPT_FTPLISTONLY: при ненулевом значении РНР будет выводить только имена файлов в FTP;
CURLOPT_FTPAPPEND: при ненулевом значении РНР будет осуществлять добавление в конец существующего удаленного FTP-файла вместо его перезаписи;
CURLOPT_NETRC: при ненулевом значении РНР будет просматривать ваш файл -./netrc в поисках вашего имени пользователя (username) и пароля (password) для осуществления доступа к удаленному сайту;
CURLOPT_FOLLOWLOCATION: при ненулевом значении перемещается согласно получаемым переадресациям, указанным в HTTP заголовках "Location: " (так как это будет происходить рекурсивно, рсдирект будет выполняться столько раз, сколько будет получено заголовков "Location: ");
CURLOPT_PUT: при ненулевом значении отсылает файл методом HTTP PUT. Параметры файла CURLOPTJNFILE и CURLOPTJNFILESIZE также должны быть указаны;
CURLOPT_MUTE: при ненулевом значении РНР будет исполнять функции CURL не выдавая сообщений;
CURLOPT_TIMEOUT: передает целочисленный (long) параметр, определяющий максимально допустимое время исполнения функций CURL в секундах;
CURLOPT_LOW_SPEED_LIMIT: передает целочисленный (long) параметр, определяющий скорость передачи данных в байтах в секунду, которая будет использоваться для проверки того, стоит ли прервать выполнение сеанса передачи при превышении им максимально допустимого времени CURLOPT_LOW_SPEED_TIME;
CURLOPT_LOW_SPEED_TIME: передает целочисленный (long) параметр, определяющий максимальное время передачи данных в секундах при скорости CURLOPT_LOW_SPEED_LIMIT, при превышении которого РНР будет прерывать выполнение операции, рассматривая ее как недопустимо медленную;
CURLOPT_RESUME_FROM: передает целочисленный (long) параметр, определяющий смещение в байтах, от которого должна начинаться передача;
CURLOPT_SSLVERSION: передает целочисленный параметр, определяющий используемую версию SSL (2 или 3). По умолчанию РНР будет пытаться самостоятельно определить ее, хотя в некоторых случаях ее следует устанавливать вручную;
CURLOPT_TIMECONDITION: передает константный параметр, определяющий смысл параметра CURLOPT_TIMEVALUE. Возможные значения: TIMECONDJFMODSINCE (но умолчанию) или TIMECONDJSUNMODSINCE. Это применимо только к HTTP; ,
CURLOPT_TIMEVALUE: передает целочисленный (long) параметр, содержащий значение времени в формате «Unix-timestamp» (число секунд с 1 января, 1970). Использование этого значения зависит от установки CURLOPTJTIMEVALUE.
Для следующих возможных значений аргумента option соответствующее значение value должно указываться в строковых значениях (тип string):

CURLOPTJJRL: адрес URL, к которому отправляется запрос. Этот параметр также можно установить при вызове функции cur1_init();
CURLOPTJJSERPWD: передает строку в формате «[username]: [password]* при подключении;
CURLOPT_PROXYUSERPWD: при подключении к HTTP прокси передает строку в формате «[username] : [password]»;
CURLOPT RANGE: передаст диапазон в формате «X-Y», где значение X или Y может быть не указано. При HTTP-передаче возможна одновременная передача нескольких интервалов, разделенных за-пятыми: «X-Y.N-M»;
CURLOPT_POSTFIELDS: передает полную строку данных, посылаемых методом HTTP POST;
CURLOPT_REFERER: передает строку, содержащую заголовок "referer", используемый в запросах HTTP;
CURLOPTJJSERAGENT: передает строку, содержащую заголовок "user-agent", используемый в запросах HTTP:
CURLOPT_FTPPORT: передает строку, содержащую значение IP-адреса, используемого инструкцией ftp "POST" для подключения к удаленному серверу FTP Эта строка может содержать простой IP-адрес, имя хоста или имя сетевого интерфейса (под UNIX), и даже символ '-', указывающий системный адрес IP, используемый по умолчанию;
CURLOPT_COOKIE: передает строку с содержимым cookie, который будет отправлен в заголовке HTTP;
CURLOPT_SSLCERT: передает строку с именем файла, содержащего SSL сертификат формата РЕМ;
CURLOPT SSLCERTPASSWD: передает строку с содержимым пароля, необходимым для использования сертификата, указанного параметром CURLOPT_SSLCERT;
CURLOPT_COOKIEFILE: передает строку с именем файла, содержащего данные cookie. Этот файл должен быть в формате Netscape или виде простого текста заголовков HTTP, сохраненного в файле;
CURLOPT _CUSTOMREQUEST: передает строку, которая будет использоваться вместо HTTP-запроса GET или HEAD. Это имеет смысл при выполнении устаревшего запроса HTTP, например DELETE.
Не пытайтесь осуществить это, не выяснив предварительно, поддерживает ли сервер указанную команду.

Для следующих возможных значений аргумента option соответствующее значение value должно указываться дескриптором, полученным от функции fopen():

CURLOPT_FILE: файл, в котором следует сохранять полученные данные. По умолчанию стандартный поток вывода: stdout;
CURLOPT_INFILE: файл, из которого следует получать данные для передачи;
CURLOPT_WRITEHEADER: файл для записи содержимого заголовков;
CURLOPT_STDERR: файл для сохранения результатов ошибок, вместо stderr.
curl_exec

Выполнение CURL сессии

bool curt_exec (int ch)

Исполняет подготовленную сессию. Эта функция должна вызываться после инициализации сессии CURL session и после того, как все параметры сессии будут установлены.

curl_ close

Закрытие сеанса

void curl_close (int ch)

Закрытие сессии с освобождением всех ресурсов (также удаляется и дескриптор сессии CURL ch).

curl_ version

Получение версии

string curl_version (void):

Возвращает текущую версию CURL.