Функция PHP curl_setopt

PHP Calendar 参考手册Справочное руководство по PHP cURL

(PHP 4 >= 4.0.2, PHP 5)

curl_setopt — Устанавливает параметр передачи cURL.


Описание

bool curl_setopt ( resource $ch , int $option , mixed $value )

Устанавливает параметр для заданного дескриптора сеанса cURL.


Parameters

ch

Дескриптор cURL, возвращаемый curl_init().

option

Устанавливаемая опция CURLOPT_XXX.

value

Значение, устанавливаемое для опции.

Для следующих необязательных параметров этих опций значение должно быть задано как значение типа bool:

Опция ЗначениеvalueЗначение Примечания
CURLOPT_AUTOREFERER При следованииLocation:перенаправлениям автоматически устанавливать заголовокReferer:информацию.
CURLOPT_BINARYTRANSFER Если включеноCURLOPT_RETURNTRANSFER, возвращать нативный (Raw) вывод.
CURLOPT_COOKIESESSION Если включено, cURL будет передавать только cookie сессии и игнорировать остальные cookie. По умолчанию cURL возвращает все cookie серверу. Сессионные cookie — это те, которые существуют для определения, действительна ли серверная сессия.
CURLOPT_CRLF Если включено, преобразовывать символы новой строки Unix в возврат каретки и перевод строки.
CURLOPT_DNS_USE_GLOBAL_CACHE Если включено, включается глобальный кэш DNS. Этот параметр потокобезопасен и включён по умолчанию.
CURLOPT_FAILONERROR Отображать коды состояния HTTP. По умолчанию игнорируются HTTP-сообщения с кодами меньше или равными 400.
CURLOPT_FILETIME Если включено, будет предпринята попытка изменить информацию в удалённом документе. Информация о результате будет возвращена через опциюCURLINFO_FILETIMEфункции curl_getinfo(). curl_getinfo().
CURLOPT_FOLLOWLOCATION Если включено, будет брать возвращённый сервером"Location: ", помещать его в заголовок и рекурсивно возвращать серверу; с помощьюCURLOPT_MAXREDIRSможно ограничить количество рекурсивных возвратов.
CURLOPT_FORBID_REUSE Принудительно разрывать соединение после завершения взаимодействия; повторное использование невозможно.
CURLOPT_FRESH_CONNECT Принудительно получать новое соединение, заменяя кэшированное.
CURLOPT_FTP_USE_EPRT Если включено, при загрузке по FTP использовать команду EPRT (или LPRT). Установка значенияFALSEотключает EPRT и LPRT и использует только команду PORT.
CURLOPT_FTP_USE_EPSV Если включено, во время FTP-передачи сначала предпринимается попытка использовать команду EPSV, прежде чем переключиться в режим PASV. Установка значенияFALSEотключает команду EPSV.
CURLOPT_FTPAPPEND Если включено, добавлять в файл, а не перезаписывать его.
CURLOPT_FTPASCII CURLOPT_TRANSFERTEXTпсевдоним для.
CURLOPT_FTPLISTONLY Если включено, выводить только имена каталогов FTP.
CURLOPT_HEADER Если включено, информация заголовочного файла выводится в виде потока данных.
CURLINFO_HEADER_OUT Если включено, трассировать строку запроса дескриптора. Доступно начиная с PHP 5.1.3.CURLINFO_Префикс указан намеренно.
CURLOPT_HTTPGET Если включено, метод HTTP устанавливается в GET. Поскольку GET является значением по умолчанию, он используется только при изменении.
CURLOPT_HTTPPROXYTUNNEL Если включено, передача через HTTP-прокси.
CURLOPT_MUTE Если включено, восстанавливает все изменённые параметры в функции cURL до значений по умолчанию.
CURLOPT_NETRC После установления соединения получите доступ~/.netrcк файлу для получения информации об имени пользователя и пароле для подключения к удалённому сайту.
CURLOPT_NOBODY Если включено, часть BODY HTML не будет выводиться.
CURLOPT_NOPROGRESS

Если включено, индикатор выполнения передачи curl отключается. Эта опция включена по умолчанию.

Примечание:

PHP автоматически устанавливает эту опцию вTRUE, эту опцию следует изменять только для отладки.

CURLOPT_NOSIGNAL Если включено, все сигналы, передаваемые curl в PHP, игнорируются. Эта опция включена по умолчанию при многопоточной передаче SAPI. Добавлено в cURL 7.10.
CURLOPT_POST Если включено, отправляется обычный POST-запрос с типом:application/x-www-form-urlencoded, как при отправке формы.
CURLOPT_PUT Если включено, разрешена отправка файлов по HTTP; также необходимо установитьCURLOPT_INFILEиCURLOPT_INFILESIZE。
CURLOPT_RETURNTRANSFER Возвращать информацию, полученную curl_exec(), в виде файлового потока вместо непосредственного вывода.
CURLOPT_SSL_VERIFYPEER Если отключено, cURL перестанет проверять сервер. ИспользуйтеCURLOPT_CAINFOопцию для указания сертификата, используйтеCURLOPT_CAPATHопцию для указания каталога сертификатовCURLOPT_SSL_VERIFYPEER(значение по умолчанию 2) включено,CURLOPT_SSL_VERIFYHOSTнеобходимо установить вTRUEиначе установить вFALSE。 По умолчанию, начиная с cURL 7.10, устанавливается вTRUE. Привязано по умолчанию начиная с cURL 7.10.
CURLOPT_TRANSFERTEXT Если включено, для FTP-передачи используется режим ASCII. Для LDAP извлекается информация в виде простого текста вместо HTML. В системах Windows система не устанавливаетSTDOUTв двоичный режим.
CURLOPT_UNRESTRICTED_AUTH При использованииCURLOPT_FOLLOWLOCATIONпродолжать добавлять имя пользователя и пароль в несколько мест в сгенерированном заголовке, даже если домен изменился.
CURLOPT_UPLOAD Если включено, разрешена загрузка файлов.
CURLOPT_VERBOSE Если включено, выводит всю информацию, сохраняемую вSTDERRили указанномCURLOPT_STDERRв.

Для следующих необязательных параметров этих опций значение должно быть установлено в виде целого числа:

Опция ЗначениеvalueЗначение Примечания
CURLOPT_BUFFERSIZE Размер кэша, считываемого из каждого полученного фрагмента данных, но нет гарантии, что это значение будет заполнено каждый раз. Добавлено в cURL 7.10.
CURLOPT_CLOSEPOLICY Либо CURLCLOSEPOLICY_LEAST_RECENTLY_USED, либо CURLCLOSEPOLICY_OLDEST. Есть еще три значения CURLCLOSEPOLICY, но cURL пока их не поддерживает.
CURLOPT_CONNECTTIMEOUT Время ожидания перед установлением соединения; если установлено в 0, ожидание бесконечно.
CURLOPT_CONNECTTIMEOUT_MS Время ожидания при попытке подключения, в миллисекундах. Если установлено значение 0, ожидает бесконечно. Добавлено в cURL 7.16.2. Доступно с PHP 5.2.3.
CURLOPT_DNS_CACHE_TIMEOUT Устанавливает время хранения DNS-информации в памяти, по умолчанию 120 секунд.
CURLOPT_FTPSSLAUTH Метод аутентификации FTP:CURLFTPAUTH_SSL(сначала попробовать SSL),CURLFTPAUTH_TLS(сначала попробовать TLS) илиCURLFTPAUTH_DEFAULT(пусть cURL решит автоматически). Добавлено в cURL 7.12.2.
CURLOPT_HTTP_VERSION CURL_HTTP_VERSION_NONE(по умолчанию, пусть cURL определит, какую версию использовать),CURL_HTTP_VERSION_1_0(принудительно HTTP/1.0) илиCURL_HTTP_VERSION_1_1(принудительно HTTP/1.1).
CURLOPT_INFILESIZE Устанавливает ограничение размера загружаемых файлов, в байтах.
CURLOPT_LOW_SPEED_LIMIT Когда скорость передачи меньше чемCURLOPT_LOW_SPEED_LIMIT(bytes/sec), PHP на основеCURLOPT_LOW_SPEED_TIMEопределит, отменять ли передачу, потому что она слишком медленная.
CURLOPT_LOW_SPEED_TIME Когда скорость передачи меньше чемCURLOPT_LOW_SPEED_LIMIT(bytes/sec), PHP на основеCURLOPT_LOW_SPEED_TIMEопределит, отменять ли передачу, потому что она слишком медленная.
CURLOPT_MAXCONNECTS Максимальное количество разрешённых соединений; при превышении будет использоватьсяCURLOPT_CLOSEPOLICY, чтобы решить, какие соединения должны быть остановлены.
CURLOPT_MAXREDIRS Задаёт максимальное количество перенаправлений HTTP. Эта опция используется вместе сCURLOPT_FOLLOWLOCATION.
CURLOPT_PORT Используется для указания порта соединения. (Необязательно)
CURLOPT_PROTOCOLS CURLPROTO_*битовая маска. Если включено, значение битовой маски ограничит, какие протоколы libcurl может использовать во время передачи. Это позволяет поддерживать множество протоколов при компиляции libcurl, но ограничить его только подмножеством разрешённых протоколов. По умолчанию libcurl будет использовать все поддерживаемые им протоколы. См.CURLOPT_REDIR_PROTOCOLS. Доступные параметры протоколов: CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_FTP, CURLPROTO_FTPS, CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_TELNET, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_TFTP, CURLPROTO_ALL Добавлено в cURL 7.19.4.
CURLOPT_PROTOCOLS CURLPROTO_*битовая маска. Если включено, значение битовой маски ограничит, какие протоколы libcurl может использовать во время передачи. Это позволяет поддерживать множество протоколов при компиляции libcurl, но ограничить его только подмножеством разрешённых протоколов. По умолчанию libcurl будет использовать все поддерживаемые им протоколы. См.CURLOPT_REDIR_PROTOCOLSДоступные параметры протоколов: CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_FTP, CURLPROTO_FTPS, CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_TELNET, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_TFTP, CURLPROTO_ALL Добавлено в cURL 7.19.4.
CURLOPT_PROXYAUTH Метод аутентификации при подключении через HTTP-прокси. ИспользуйтеCURLOPT_HTTPAUTHбитовые флаги, чтобы задать соответствующий параметр. Для аутентификации через прокси поддерживаются толькоCURLAUTH_BASICиCURLAUTH_NTLMв настоящее время поддерживается. Добавлено в cURL 7.10.7.
CURLOPT_PROXYPORT Порт прокси-сервера. Порт также может бытьCURLOPT_PROXYзадан в
CURLOPT_PROXYTYPE не являетсяCURLPROXY_HTTP(значение по умолчанию) илиCURLPROXY_SOCKS5。 Добавлено в cURL 7.10.
CURLOPT_REDIR_PROTOCOLS CURLPROTO_*Значение битового поля. Если включено, значение битового поля ограничит поток передачиCURLOPT_FOLLOWLOCATIONпротоколами, которые можно использовать при следовании перенаправлению. Это позволит ограничить поток передачи подмножеством разрешённых протоколов во время перенаправлений. По умолчанию libcurl будет разрешать все протоколы, кроме FILE и SCP. Это несколько отличается от предварительной версии 7.19.4, которая безоговорочно следовала всем поддерживаемым протоколам. О константах протоколов см.CURLOPT_PROTOCOLS。 Добавлено в cURL 7.19.4.
CURLOPT_RESUME_FROM Передайте смещение в байтах при возобновлении передачи (используется для возобновления прерванных передач).
CURLOPT_SSL_VERIFYHOST 1 Проверяет, существует ли общее имя (Common Name) в SSL-сертификате сервера. Примечание переводчика: Common Name обычно относится к домену или поддомену, для которого вы собираетесь получить SSL-сертификат. 2 Проверяет, существует ли общее имя и совпадает ли оно с указанным именем хоста.
CURLOPT_SSLVERSION Используемая версия SSL (2 или 3). По умолчанию PHP определит это значение сам, хотя в некоторых случаях его нужно задать вручную.
CURLOPT_TIMECONDITION ЕслиCURLOPT_TIMEVALUEбыл изменён после указанного времени, используйтеCURL_TIMECOND_IFMODSINCEдля возврата страницы; если он не был изменён, иCURLOPT_HEADERистинно, вернуть"304 Not Modified"заголовок,CURLOPT_HEADERложно, используйтеCURL_TIMECOND_IFUNMODSINCE, по умолчанию используетсяCURL_TIMECOND_IFUNMODSINCE。
CURLOPT_TIMEOUT Задайте максимальное количество секунд, в течение которых cURL может выполняться.
CURLOPT_TIMEOUT_MS Задайте максимальное количество миллисекунд, в течение которых cURL разрешено выполняться. Добавлено в cURL 7.16.2. Доступно с PHP 5.2.3.
CURLOPT_TIMEVALUE УстановитеCURLOPT_TIMECONDITIONметку времени для использования; по умолчанию используетсяCURL_TIMECOND_IFMODSINCE。

Для следующих параметров параметру value следует присвоить строковое значение:

Опция НеобязательноезначениеЗначение Примечания
CURLOPT_CAINFO Имя файла, содержащего один или несколько сертификатов для проверки сервера. Этот параметр имеет смысл только при использовании сCURLOPT_SSL_VERIFYPEERОн имеет смысл только при совместном использовании.
CURLOPT_CAPATH Каталог, содержащий несколько сертификатов CA. Эта опция используется сCURLOPT_SSL_VERIFYPEERОна используется вместе.
CURLOPT_COOKIE Установите"Cookie: "часть HTTP-запроса. Несколько cookie разделяются точками с запятой, после точки с запятой ставится пробел (например, "fruit=apple; colour=red")。
CURLOPT_COOKIEFILE Имя файла, содержащего данные cookie. Формат файла cookie может быть форматом Netscape или просто информацией из HTTP-заголовков, сохранённой в файле.
CURLOPT_COOKIEJAR Файл, в который сохраняется информация cookie после завершения соединения.
CURLOPT_CUSTOMREQUEST

Использовать пользовательское сообщение запроса вместо"GET"или"HEAD"в качестве HTTP-запроса. Это полезно для выполнения"DELETE"или другие более редкие HTTP-запросы. Допустимые значения включают"GET","POST","CONNECT"и т.д. То есть не вводите здесь весь HTTP-запрос. Например, ввод"GET /index.html HTTP/1.0\r\n\r\n"неверно.

Примечание:

Не используйте это, не убедившись, что сервер поддерживает этот пользовательский метод запроса.

CURLOPT_EGDSOCKET АналогичноCURLOPT_RANDOM_FILE, но вместо этого — сокет Entropy Gathering Daemon.
CURLOPT_ENCODING В заголовке HTTP-запроса"Accept-Encoding: "значение. Поддерживаемые кодировки:"identity","deflate"и"gzip". Если пустая строка"", заголовок запроса отправит все поддерживаемые типы кодирования. Добавлено в cURL 7.10.
CURLOPT_FTPPORT Это значение будет использоваться для получения IP-адреса, необходимого для команды FTP "POST". Команда "POST" указывает удаленному серверу подключиться к IP-адресу, который мы указываем. Эта строка может быть IP-адресом в виде простого текста, именем хоста, именем сетевого интерфейса (в UNIX) или просто '-' для использования IP-адреса по умолчанию.
CURLOPT_INTERFACE Имя сетевого интерфейса для отправки; это может быть имя интерфейса, IP-адрес или имя хоста.
CURLOPT_KRB4LEVEL Уровень безопасности KRB4 (Kerberos 4). Любое из следующих значений допустимо (в порядке от низкого к высокому):"clear"、"safe"、"confidential"、"private".. Если строка не совпадает ни с одним из них, будет использоваться"private". Если для этой опции задано значениеNULL, это отключит аутентификацию безопасности KRB4. В настоящее время аутентификация безопасности KRB4 может использоваться только для FTP-передач.
CURLOPT_POSTFIELDS Все данные отправляются с использованием операции "POST" в протоколе HTTP. Чтобы отправить файл, добавьте к имени файла префикс@prefix и используйте полный путь. Этот параметр может быть строкой в формате urlencoded, похожей на 'para1=val1&para2=val2&...', или массивом, где имена полей являются ключами, а данные полей — значениями. Еслиvalueявляется массивом,Content-Typeзаголовок будет установлен вmultipart/form-data。
CURLOPT_PROXY Туннель HTTP-прокси.
CURLOPT_PROXYUSERPWD A"[username]:[password]"строка формата, используемая для подключения к прокси.
CURLOPT_RANDOM_FILE Имя файла, используемое для генерации начального числа генератора случайных чисел SSL.
CURLOPT_RANGE с"X-Y"в форме, где X и Y необязательны и задают диапазон данных для загрузки в байтах. Поток HTTP-передачи также поддерживает несколько таких повторяющихся элементов, разделённых запятыми, например"X-Y,N-M"。
CURLOPT_REFERER В заголовке HTTP-запроса"Referer: "содержимое.
CURLOPT_SSL_CIPHER_LIST Список алгоритмов шифрования SSL. Например,RC4-SHAиTLSv1— все доступные списки шифрования.
CURLOPT_SSLCERT Имя файла, содержащего сертификат в формате PEM.
CURLOPT_SSLCERTPASSWD ИспользуйтеCURLOPT_SSLCERTпароль, требуемый сертификатом.
CURLOPT_SSLCERTTYPE Тип сертификата. Поддерживаемые форматы:"PEM"(по умолчанию),"DER"и"ENG"。 Добавлено в cURL 7.9.3.
CURLOPT_SSLENGINE Используется вCURLOPT_SSLKEYпеременная механизма шифрования для закрытого ключа SSL, указанного в
CURLOPT_SSLENGINE_DEFAULT Переменная, используемая для операций асимметричного шифрования.
CURLOPT_SSLKEY Имя файла, содержащего закрытый ключ SSL.
CURLOPT_SSLKEYPASSWD

ВCURLOPT_SSLKEYПароль для закрытого ключа SSL, указанного в

Примечание:

Поскольку эта опция содержит конфиденциальную информацию о пароле, не забудьте обеспечить безопасность этого PHP-скрипта.

CURLOPT_SSLKEYTYPE CURLOPT_SSLKEYТип шифрования закрытого ключа, указанного в ... Поддерживаемые типы ключей:"PEM"(по умолчанию),"DER"и"ENG"。
CURLOPT_URL URL-адрес для загрузки, который также можно задать вcurl_init()функции.
CURLOPT_USERAGENT Включите"User-Agent: "строку заголовка в HTTP-запрос.
CURLOPT_USERPWD Передайте имя пользователя и пароль, необходимые для подключения, в формате:"[username]:[password]"。

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

Опция НеобязательноезначениеЗначение Примечания
CURLOPT_HTTP200ALIASES Массив кодов ответа, которые следует считать кодом 200. Коды ответа в массиве считаются корректными ответами, в противном случае они считаются ошибками. Добавлено в cURL 7.10.3.
CURLOPT_HTTPHEADER Массив, используемый для установки полей HTTP-заголовка. Используйте массив в следующем виде: array('Content-type: text/plain', 'Content-length: 100')
CURLOPT_POSTQUOTE Набор FTP-команд для выполнения на сервере после выполнения FTP-запроса.
CURLOPT_QUOTE Набор FTP-команд для выполнения на сервере перед FTP-запросом.

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

Опция НеобязательноезначениеЗначение
CURLOPT_FILE Задает расположение выходного файла; значение имеет тип resource, по умолчанию используетсяSTDOUT(браузер).
CURLOPT_INFILE Расположение файла, из которого выполняется чтение при загрузке файла; значение имеет тип resource.
CURLOPT_STDERR Задает расположение вывода ошибок; значение имеет тип resource, заменяя стандартныйSTDERR。
CURLOPT_WRITEHEADER Задает расположение файла для записи содержимого раздела заголовков; значение имеет тип resource.

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

Опция НеобязательноезначениеЗначение
CURLOPT_HEADERFUNCTION Задает функцию обратного вызова с двумя параметрами: первый — дескриптор ресурса cURL, второй — выводимые данные заголовка. Вывод данных заголовка должен выполняться через эту функцию. Возвращает размер записанных данных.
CURLOPT_PASSWDFUNCTION Задает функцию обратного вызова с тремя параметрами: первый — дескриптор ресурса cURL, второй — приглашение для ввода пароля, а третий — максимально допустимая длина пароля. Возвращает значение пароля.
CURLOPT_PROGRESSFUNCTION Установите функцию обратного вызова с тремя параметрами: первый — дескриптор ресурса cURL, второй — ресурс файлового дескриптора, третий — длина. Возвращает содержащиеся данные.
CURLOPT_READFUNCTION Имя функции обратного вызова. Эта функция должна принимать три параметра. Первый — ресурс cURL; второй — потоковый ресурс, переданный через опциюCURLOPT_INFILEв cURL; третий параметр — максимальный объём данных, который может быть прочитан. Функция обратного вызова должна возвращать строку длиной не больше запрошенного количества данных (третьего параметра). Обычно читается из переданного потокового ресурса. Возврат пустой строки какEOF(конец файла) — сигнал.
CURLOPT_WRITEFUNCTION Имя функции обратного вызова. Эта функция должна принимать два параметра. Первый — ресурс cURL; второй — строка данных для записи. Данные должны быть сохранены в функции. Функция должна возвращать точное количество байтов переданных данных, которые нужно записать, иначе передача будет прервана ошибкой.

Возвращаемые значения

Возвращает TRUE при успехе или FALSE при неудаче.


История изменений

Version Описание
5.2.10 ВведеноCURLOPT_PROTOCOLS, и CURLOPT_REDIR_PROTOCOLS.
5.1.0 ВведеноCURLOPT_AUTOREFERER, CURLOPT_BINARYTRANSFER, CURLOPT_FTPSSLAUTH, CURLOPT_PROXYAUTH, и CURLOPT_TIMECONDITION.
5.0.0 ВведеноCURLOPT_FTP_USE_EPRT, CURLOPT_NOSIGNAL, CURLOPT_UNRESTRICTED_AUTH, CURLOPT_BUFFERSIZE, CURLOPT_HTTPAUTH, CURLOPT_PROXYPORT, CURLOPT_PROXYTYPE, CURLOPT_SSLCERTTYPE, и CURLOPT_HTTP200ALIASES.

Примеры

Инициализация нового сеанса cURL и загрузка веб-страницы

<?php
// 创建一个新cURL资源
$ch = curl_init();

// 设置URL和相应的选项
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, false);

// 抓取URL并把它传递给浏览器
curl_exec($ch);

//关闭cURL资源,并且释放系统资源
curl_close($ch);
?>

Пример загрузки файла:

<?php

/* http://localhost/upload.php:
print_r($_POST);
print_r($_FILES);
*/

$ch = curl_init();

$data = array('name' => 'Foo', 'file' => '@/home/user/test.png');

curl_setopt($ch, CURLOPT_URL, 'http://localhost/upload.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

curl_exec($ch);
?>

Приведённый выше пример выведет:

Array
(
    [name] => Foo
)
Array
(
    [file] => Array
        (
            [name] => test.png
            [type] => image/png
            [tmp_name] => /tmp/phpcpjNeQ
            [error] => 0
            [size] => 279
        )

)


Примечания

Передача массива в CURLOPT_POSTFIELDS приведёт к тому, что cURL закодирует данные как multipart/form-data, а передача строки, закодированной в URL, приведёт к тому, что данные будут закодированы как application/x-www-form-urlencoded.


PHP Calendar 参考手册Справочник по PHP cURL

Другие расширения