首頁>網絡編程教程>PHP教程

PHP curl_setopt函數

作者：Eve Cole 更新時間：2025-01-06 12:36:01

(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_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設定成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_FTPAPS、RLRLPROTO_ICT_、CURLPROTOD、ATOCU在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_FTPAPS、RLRLPROTO_ICT_、CURLPROTOD、ATOCU在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 檢查伺服器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，則使用CUn_TIME ，預設值為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.0rnrn"是不正確的。

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-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私鑰的密碼。

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 , CURJPT_BURLOPT_PROXYPORT , 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-encoded字串時，資料會被編碼成application/x-www-form-urlencoded。

相關文章