Latest web development tutorials

PHP curl_setopt函數

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會話句柄設置一個選項。


參數

ch

由curl_init() 返回的cURL 句柄。

option

需要設置的CURLOPT_XXX選項。

value

將設置在option選項上的值。

對於下面的這些option的可選參數,value應該被設置一個bool類型的值:

選項 可選value 備註
CURLOPT_AUTOREFERER 當根據Location:重定向時,自動設置header中的Referer:信息。
CURLOPT_BINARYTRANSFER 在啟用CURLOPT_RETURNTRANSFER的時候,返回原生的(Raw)輸出。
CURLOPT_COOKIESESSION 啟用時curl會僅僅傳遞一個session cookie,忽略其他的cookie,默認狀況下cURL會將所有的cookie返回給服務端。 session cookie是指那些用來判斷服務器端的session是否有效而存在的cookie。
CURLOPT_CRLF 啟用時將Unix的換行符轉換成回車換行符。
CURLOPT_DNS_USE_GLOBAL_CACHE 啟用時會啟用一個全局的DNS緩存,此項為線程安全的,並且默認啟用。
CURLOPT_FAILONERROR 顯示HTTP狀態碼,默認行為是忽略編號小於等於400的HTTP信息。
CURLOPT_FILETIME 啟用時會嘗試修改遠程文檔中的信息。 結果信息會通過curl_getinfo()函數的CURLINFO_FILETIME選項返回。 curl_getinfo().
CURLOPT_FOLLOWLOCATION 啟用時會將服務器服務器返回的"Location: "放在header中遞歸的返回給服務器,使用CURLOPT_MAXREDIRS可以限定遞歸返回的數量。
CURLOPT_FORBID_REUSE 在完成交互以後強迫斷開連接,不能重用。
CURLOPT_FRESH_CONNECT 強制獲取一個新的連接,替代緩存中的連接。
CURLOPT_FTP_USE_EPRT 啟用時當FTP下載時,使用EPRT (或LPRT)命令。 設置為FALSE時禁用EPRT和LPRT,使用PORT命令only.
CURLOPT_FTP_USE_EPSV 啟用時,在FTP傳輸過程中回復到PASV模式前首先嘗試EPSV命令。 設置為FALSE時禁用EPSV命令。
CURLOPT_FTPAPPEND 啟用時追加寫入文件而不是覆蓋它。
CURLOPT_FTPASCII CURLOPT_TRANSFERTEXT的別名。
CURLOPT_FTPLISTONLY 啟用時只列出FTP目錄的名字。
CURLOPT_HEADER 啟用時會將頭文件的信息作為數據流輸出。
CURLINFO_HEADER_OUT 啟用時追踪句柄的請求字符串。 從PHP 5.1.3 開始可用。 CURLINFO_前綴是故意的(intentional)。
CURLOPT_HTTPGET 啟用時會設置HTTP的method為GET,因為GET是默認是,所以只在被修改的情況下使用。
CURLOPT_HTTPPROXYTUNNEL 啟用時會通過HTTP代理來傳輸。
CURLOPT_MUTE 啟用時將cURL函數中所有修改過的參數恢復默認值。
CURLOPT_NETRC 在連接建立以後,訪問~/.netrc文件獲取用戶名和密碼信息連接遠程站點。
CURLOPT_NOBODY 啟用時將不對HTML中的BODY部分進行輸出。
CURLOPT_NOPROGRESS

啟用時關閉curl傳輸的進度條,此項的默認設置為啟用。

Note :

PHP自動地設置這個選項為TRUE ,這個選項僅僅應當在以調試為目的時被改變。

CURLOPT_NOSIGNAL 啟用時忽略所有的curl傳遞給php進行的信號。 在SAPI多線程傳輸時此項被默認啟用。 cURL 7.10時被加入。
CURLOPT_POST 啟用時會發送一個常規的POST請求,類型為: application/x-www-form-urlencoded ,就像表單提交的一樣。
CURLOPT_PUT 啟用時允許HTTP發送文件,必須同時設置CURLOPT_INFILECURLOPT_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設置成binary模式。
CURLOPT_UNRESTRICTED_AUTH 在使用CURLOPT_FOLLOWLOCATION產生的header中的多個locations中持續追加用戶名和密碼信息,即使域名已發生改變。
CURLOPT_UPLOAD 啟用後允許文件上傳。
CURLOPT_VERBOSE 啟用時會匯報所有的信息,存放在STDERR或指定的CURLOPT_STDERR中。

對於下面的這些option的可選參數,value應該被設置一個integer類型的值:

選項 可選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 設定上傳文件的大小限制,字節(byte)為單位。
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_BASICCURLAUTH_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 檢查服務器SSL證書中是否存在一個公用名(common name)。 譯者註:公用名(Common Name)一般來講就是填寫你將要申請SSL證書的域名(domain)或子域名(sub domain)。 2 檢查公用名是否存在,並且是否與提供的主機名匹配。
CURLOPT_SSLVERSION 使用的SSL版本(2 或3)。 默認情況下PHP會自己檢測這個值,儘管有些情況下需要手動地進行設置。
CURLOPT_TIMECONDITION 如果在CURLOPT_TIMEVALUE指定的某個時間以後被編輯過,則使用CURL_TIMECOND_IFMODSINCE返回頁面,如果沒有被修改過,並且CURLOPT_HEADER為true,則返回一個"304 Not Modified"的header, CURLOPT_HEADER為false,則使用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

對於下面的這些option的可選參數,value應該被設置一個string類型的值:

選項 可選value 備註
CURLOPT_CAINFO 一個保存著1個或多個用來讓服務端驗證的證書的文件名。 這個參數僅僅在和CURLOPT_SSL_VERIFYPEER一起使用時才有意義。 .
CURLOPT_CAPATH 一個保存著多個CA證書的目錄。 這個選項是和CURLOPT_SSL_VERIFYPEER一起使用的。
CURLOPT_COOKIE 設定HTTP請求中"Cookie: "部分的內容。 多個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"是不正確的。

Note :

在確定服務器支持這個自定義請求的方法前不要使用。

CURLOPT_EGDSOCKET 類似CURLOPT_RANDOM_FILE ,除了一個Entropy Gathering Daemon套接字。
CURLOPT_ENCODING HTTP請求頭中"Accept-Encoding: "的值。 支持的編碼有"identity""deflate""gzip" 。 如果為空字符串"" ,請求頭會發送所有支持的編碼類型。 在cURL 7.10中被加入。
CURLOPT_FTPPORT 這個值將被用來獲取供FTP"POST"指令所需要的IP地址。 "POST"指令告訴遠程服務器連接到我們指定的IP地址。 這個字符串可以是純文本的IP地址、主機名、一個網絡接口名(UNIX下)或者只是一個'-'來使用默認的IP地址。
CURLOPT_INTERFACE 網絡發送接口名,可以是一個接口名、IP地址或者是一個主機名。
CURLOPT_KRB4LEVEL KRB4 (Kerberos 4) 安全級別。 下面的任何值都是有效的(從低到高的順序): "clear""safe""confidential""private". 。 如果字符串和這些都不匹配,將使用"private" 。 這個選項設置為NULL時將禁用KRB4安全認證。 目前KRB4 安全認證只能用於FTP傳輸。
CURLOPT_POSTFIELDS 全部數據使用HTTP協議中的"POST"操作來發送。 要發送文件,在文件名前面加上@前綴並使用完整路徑。 這個參數可以通過urlencoded後的字符串類似' para1=val1&para2=val2&... '或使用一個以字段名為鍵值,字段數據為值的數組。 如果value是一個數組, Content-Type頭將會被設置成multipart/form-data
CURLOPT_PROXY HTTP代理通道。
CURLOPT_PROXYUSERPWD 一個用來連接到代理的"[username]:[password]"格式的字符串。
CURLOPT_RANDOM_FILE 一個被用來生成SSL隨機數種子的文件名。
CURLOPT_RANGE "XY"的形式,其中X和Y都是可選項獲取數據的範圍,以字節計。 HTTP傳輸線程也支持幾個這樣的重複項中間用逗號分隔如"XY,NM"
CURLOPT_REFERER 在HTTP請求頭中"Referer: "的內容。
CURLOPT_SSL_CIPHER_LIST 一個SSL的加密算法列表。 例如RC4-SHATLSv1都是可用的加密列表。
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私鑰的密碼。

Note :

由於這個選項包含了敏感的密碼信息,記得保證這個PHP腳本的安全。

CURLOPT_SSLKEYTYPE CURLOPT_SSLKEY中規定的私鑰的加密類型,支持的密鑰類型為"PEM" (默認值)、 "DER""ENG"
CURLOPT_URL 需要獲取的URL地址,也可以在curl_init()函數中設置。
CURLOPT_USERAGENT 在HTTP請求中包含一個"User-Agent: "頭的字符串。
CURLOPT_USERPWD 傳遞一個連接中需要的用戶名和密碼,格式為: "[username]:[password]"

對於下面的這些option的可選參數,value應該被設置一個數組:

選項 可選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命令。

對於下面的這些option的可選參數,value應該被設置一個流資源(例如使用fopen()):

選項 可選value
CURLOPT_FILE 設置輸出文件的位置,值是一個資源類型,默認為STDOUT (瀏覽器)。
CURLOPT_INFILE 在上傳文件的時候需要讀取的文件地址,值是一個資源類型。
CURLOPT_STDERR 設置一個錯誤輸出地址,值是一個資源類型,取代默認的STDERR
CURLOPT_WRITEHEADER 設置header部分內容的寫入的文件地址,值是一個資源類型。

對於下面的這些option的可選參數,value應該被設置為一個回調函數名:

選項 可選value
CURLOPT_HEADERFUNCTION 設置一個回調函數,這個函數有兩個參數,第一個是cURL的資源句柄,第二個是輸出的header數據。 header數據的輸出必須依賴這個函數,返回已寫入的數據大小。
CURLOPT_PASSWDFUNCTION 設置一個回調函數,有三個參數,第一個是cURL的資源句柄,第二個是一個密碼提示符,第三個參數是密碼長度允許的最大值。 返回密碼的值。
CURLOPT_PROGRESSFUNCTION 設置一個回調函數,有三個參數,第一個是cURL的資源句柄,第二個是一個文件描述符資源,第三個是長度。 返回包含的數據。
CURLOPT_READFUNCTION 回調函數名。 該函數應接受三個參數。 第一個是cURL resource;第二個是通過選項CURLOPT_INFILE傳給cURL的stream resource;第三個參數是最大可以讀取的數據的數量。 回調函數必須返回一個字符串,長度小於或等於請求的數據量(第三個參數)。 一般從傳入的stream resource 讀取。 返回空字符串作為EOF (文件結束)信號。
CURLOPT_WRITEFUNCTION 回調函數名。 該函數應接受兩個參數。 第一個是cURL resource;第二個是要寫入的數據字符串。 數據必須在函數中被保存。 函數必須返回準確的傳入的要寫入數據的字節數,否則傳輸會被一個錯誤所中斷。

返回值

成功時返回TRUE, 或者在失敗時返回FALSE。


更新日誌

版本 說明
5.2.10 引入CURLOPT_PROTOCOLS , and CURLOPT_REDIR_PROTOCOLS .
5.1.0 引入CURLOPT_AUTOREFERER , CURLOPT_BINARYTRANSFER , CURLOPT_FTPSSLAUTH , CURLOPT_PROXYAUTH , and CURLOPT_TIMECONDITION .
5.0.0 引入CURLOPT_FTP_USE_EPRT , CURLOPT_NOSIGNAL , CURLOPT_UNRESTRICTED_AUTH , CURLOPT_BUFFERSIZE , CURLOPT_HTTPAUTH , CURLOPT_PROXYPORT , CURLOPT_PROXYTYPE , CURLOPT_SSLCERTTYPE , and 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-encoded字符串時,數據會被編碼成application/x-www-form-urlencoded。


PHP Calendar 參考手冊 PHP cURL參考手冊