# PHP curl_setopt函數 (PHP 4 &gt;= 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** | 在連接建立以后，訪問&lt;var class="filename"&gt;~/.netrc&lt;/var&gt;文件獲取用戶名和密碼信息連接遠程站點。 | | **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_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 檢查服務器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** | 以_"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私鑰的密碼。**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。