(PHP 4 >= 4.0.2, PHP 5)
curl_setopt — Set a cURL transport option.
bool curl_setopt ( resource $ch , int $option , mixed $value )
Sets an option for the given cURL session handle.
ch
The cURL handle returned by curl_init().
option
CURLOPT_XXX options need to be set.
value
The value that will be set on option.
For the optional parameters of the following options, value should be set to a bool type value:
| Options | Optional value | Remark |
|---|---|---|
| CURLOPT_AUTOREFERER | When redirecting based on Location:, the Referer: information in the header is automatically set. | |
| CURLOPT_BINARYTRANSFER | Returns raw output when CURLOPT_RETURNTRANSFER is enabled. | |
| CURLOPT_COOKIESESSION | When enabled, curl will only pass one session cookie and ignore other cookies. By default, curl will return all cookies to the server. Session cookies refer to cookies that are used to determine whether the server-side session is valid. | |
| CURLOPT_CRLF | When enabled, converts Unix newlines to carriage returns and linefeeds. | |
| CURLOPT_DNS_USE_GLOBAL_CACHE | When enabled, a global DNS cache is enabled. This is thread-safe and enabled by default. | |
| CURLOPT_FAILONERROR | Displays the HTTP status code. The default behavior is to ignore HTTP messages with numbers less than or equal to 400. | |
| CURLOPT_FILETIME | When enabled, attempts to modify information in the remote document. The result information will be returned through the CURLINFO_FILETIME option of the curl_getinfo() function. curl_getinfo(). | |
| CURLOPT_FOLLOWLOCATION | When enabled, the "Location:" returned by the server will be placed in the header and returned to the server recursively. Use CURLOPT_MAXREDIRS to limit the number of recursive returns. | |
| CURLOPT_FORBID_REUSE | The connection is forced to disconnect after the interaction is completed and cannot be reused. | |
| CURLOPT_FRESH_CONNECT | Forces a new connection to be obtained, replacing the one in the cache. | |
| CURLOPT_FTP_USE_EPRT | When enabled, use the EPRT (or LPRT) command when FTP downloads. When set to FALSE disables EPRT and LPRT, use the PORT command only. | |
| CURLOPT_FTP_USE_EPSV | When enabled, EPSV commands are first attempted before reverting to PASV mode during FTP transfers. Disables the EPSV command when set to FALSE . | |
| CURLOPT_FTPAPPEND | When enabled append writes to the file instead of overwriting it. | |
| CURLOPT_FTPASCII | Alias for CURLOPT_TRANSFERTEXT . | |
| CURLOPT_FTPLISTONLY | When enabled, only the names of FTP directories are listed. | |
| CURLOPT_HEADER | When enabled, the header file information will be output as a data stream. | |
| CURLINFO_HEADER_OUT | Request string for tracing handles when enabled. | Available starting with PHP 5.1.3. The CURLINFO_ prefix is intentional. |
| CURLOPT_HTTPGET | When enabled, the HTTP method will be set to GET. Because GET is the default, it will only be used if it is modified. | |
| CURLOPT_HTTPPROXYTUNNEL | When enabled, transmission is via an HTTP proxy. | |
| CURLOPT_MUTE | When enabled, all modified parameters in the cURL function will be restored to their default values. | |
| CURLOPT_NETRC | After the connection is established, access the ~/.netrc file to obtain the username and password information to connect to the remote site. | |
| CURLOPT_NOBODY | When enabled, the BODY part of the HTML will not be output. | |
| CURLOPT_NOPROGRESS | Turn off the progress bar of curl transfer when enabled. The default setting of this item is enabled.
| |
| CURLOPT_NOSIGNAL | When enabled, ignores all signals passed by curl to php. This item is enabled by default during SAPI multi-threaded transmission. | Added in cURL 7.10. |
| CURLOPT_POST | When enabled, a regular POST request of type: application/x-www-form-urlencoded will be sent, just like a form submission. | |
| CURLOPT_PUT | When enabled to allow HTTP to send files, both CURLOPT_INFILE and CURLOPT_INFILESIZE must be set. | |
| CURLOPT_RETURNTRANSFER | Return the information obtained by curl_exec() in the form of a file stream instead of outputting it directly. | |
| CURLOPT_SSL_VERIFYPEER | When disabled cURL will terminate validation from the server. Set the certificate using the CURLOPT_CAINFO option. Set the certificate directory using the CURLOPT_CAPATH option. If CURLOPT_SSL_VERIFYPEER (default 2) is enabled, CURLOPT_SSL_VERIFYHOST needs to be set to TRUE otherwise set to FALSE . | Defaults to TRUE since cURL 7.10. Starting with cURL 7.10, bundle installation is defaulted. |
| CURLOPT_TRANSFERTEXT | When enabled, uses ASCII mode for FTP transfers. For LDAP, it retrieves plain text information rather than HTML. On Windows systems, the system does not set STDOUT to binary mode. | |
| CURLOPT_UNRESTRICTED_AUTH | Continuously append username and password information to multiple locations in the header generated using CURLOPT_FOLLOWLOCATION , even if the domain name has changed. | |
| CURLOPT_UPLOAD | Allow file uploads when enabled. | |
| CURLOPT_VERBOSE | When enabled, all information will be reported and stored in STDERR or the specified CURLOPT_STDERR . |
For the optional parameters of the following options, value should be set to a value of type integer:
| Options | Optional value | Remark |
|---|---|---|
| CURLOPT_BUFFERSIZE | The size of the cache is read into the data obtained each time, but there is no guarantee that this value will be filled every time. | Added in cURL 7.10. |
| CURLOPT_CLOSEPOLICY | Either CURLCLOSEPOLICY_LEAST_RECENTLY_USED or CURLCLOSEPOLICY_OLDEST, there are three other CURLCLOSEPOLICYs, but cURL does not support them yet. | |
| CURLOPT_CONNECTTIMEOUT | The time to wait before initiating a connection. If set to 0, it will wait indefinitely. | |
| CURLOPT_CONNECTTIMEOUT_MS | The time to wait for a connection attempt, in milliseconds. If set to 0, wait infinitely. | Added in cURL 7.16.2. Available starting with PHP 5.2.3. |
| CURLOPT_DNS_CACHE_TIMEOUT | Set the time to save DNS information in memory, the default is 120 seconds. | |
| CURLOPT_FTPSSLAUTH | FTP authentication method: CURLFTPAUTH_SSL (try SSL first), CURLFTPAUTH_TLS (try TLS first) or CURLFTPAUTH_DEFAULT (let cURL decide automatically). | Added in cURL 7.12.2. |
| CURLOPT_HTTP_VERSION | CURL_HTTP_VERSION_NONE (default, lets curl decide which version to use), CURL_HTTP_VERSION_1_0 (forces HTTP/1.0) or CURL_HTTP_VERSION_1_1 (forces HTTP/1.1). | |
| CURLOPT_INFILESIZE | Set the size limit of uploaded files in bytes. | |
| CURLOPT_LOW_SPEED_LIMIT | When the transmission speed is less than CURLOPT_LOW_SPEED_LIMIT (bytes/sec), PHP will use CURLOPT_LOW_SPEED_TIME to determine whether to cancel the transmission because it is too slow. | |
| CURLOPT_LOW_SPEED_TIME | When the transmission speed is less than CURLOPT_LOW_SPEED_LIMIT (bytes/sec), PHP will use CURLOPT_LOW_SPEED_TIME to determine whether to cancel the transmission because it is too slow. | |
| CURLOPT_MAXCONNECTS | The maximum number of connections allowed, if exceeded, CURLOPT_CLOSEPOLICY will be used to determine which connections should be stopped. | |
| CURLOPT_MAXREDIRS | Specifies the maximum number of HTTP redirects. This option is used with CURLOPT_FOLLOWLOCATION . | |
| CURLOPT_PORT | Used to specify the connection port. (optional) | |
| CURLOPT_PROTOCOLS | Bitfield refers to CURLPROTO_* . If enabled, the bitfield value limits which protocols libcurl can use during transfers. This will allow you to compile libcurl with support for many protocols, but be restricted to using only a subset of them that are allowed to be used. By default libcurl will use all protocols it supports. See CURLOPT_REDIR_PROTOCOLS .The available protocol options are: 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 | Added in cURL 7.19.4. |
| CURLOPT_PROTOCOLS | Bitfield refers to CURLPROTO_* . If enabled, the bitfield value limits which protocols libcurl can use during transfers. This will allow you to compile libcurl to support many protocols, but only to use a subset of them that are allowed to be used. By default libcurl will use all protocols it supports. See CURLOPT_REDIR_PROTOCOLS .The available protocol options are: 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 | Added in cURL 7.19.4. |
| CURLOPT_PROXYAUTH | Verification method for HTTP proxy connections. Use the bitfield flags in CURLOPT_HTTPAUTH to set the corresponding options. For proxy authentication only CURLAUTH_BASIC and CURLAUTH_NTLM are currently supported. | Added in cURL 7.10.7. |
| CURLOPT_PROXYPORT | The port of the proxy server. The port can also be set in CURLOPT_PROXY . | |
| CURLOPT_PROXYTYPE | Either CURLPROXY_HTTP (default) or CURLPROXY_SOCKS5 . | Added in cURL 7.10. |
| CURLOPT_REDIR_PROTOCOLS | Bitfield value in CURLPROTO_* . If enabled, the bitfield value will limit the protocols that the transport thread can use when following a redirect when CURLOPT_FOLLOWLOCATION is enabled. This will allow you to restrict the transport thread to a subset of allowed protocols when redirecting. By default libcurl will allow all protocols except FILE and SCP. This is slightly different from the 7.19.4 pre-release version which unconditionally follows all supported protocols. For protocol constants, please refer to CURLOPT_PROTOCOLS . | Added in cURL 7.19.4. |
| CURLOPT_RESUME_FROM | Pass a byte offset when resuming the transfer (used for resume transfer). | |
| CURLOPT_SSL_VERIFYHOST | 1 Check whether there is a common name in the server SSL certificate. Translator's Note: Common Name (Common Name) generally means filling in the domain name (domain) or subdomain (sub domain) for which you are going to apply for an SSL certificate. 2 Check that the common name exists and matches the provided host name. | |
| CURLOPT_SSLVERSION | SSL version to use (2 or 3). By default PHP will detect this value by itself, although in some cases it may need to be set manually. | |
| CURLOPT_TIMECONDITION | If it has been edited after a certain time specified by CURLOPT_TIMEVALUE , use CURL_TIMECOND_IFMODSINCE to return the page. If it has not been modified and CURLOPT_HEADER is true, a "304 Not Modified" header is returned. If CURLOPT_HEADER is false, use CURL_TIMECOND_IFUNMODSINCE. , the default value is CURL_TIMECOND_IFUNMODSINCE . | |
| CURLOPT_TIMEOUT | Set the maximum number of seconds cURL is allowed to execute. | |
| CURLOPT_TIMEOUT_MS | Sets the maximum number of milliseconds that cURL is allowed to execute. | Added in cURL 7.16.2. Available from PHP 5.2.3 onwards. |
| CURLOPT_TIMEVALUE | Set a timestamp used by CURLOPT_TIMECONDITION . By default, CURL_TIMECOND_IFMODSINCE is used. |
For the optional parameters of the following options, value should be set to a string type value:
| Options | Optional value | Remark |
|---|---|---|
| CURLOPT_CAINFO | The name of a file that holds one or more certificates for verification by the server. This parameter is only meaningful when used with CURLOPT_SSL_VERIFYPEER . . | |
| CURLOPT_CAPATH | A directory that holds multiple CA certificates. This option is used with CURLOPT_SSL_VERIFYPEER . | |
| CURLOPT_COOKIE | Set the content of the "Cookie:" part of the HTTP request. Multiple cookies are separated by a semicolon followed by a space (for example, " fruit=apple; color=red "). | |
| CURLOPT_COOKIEFILE | The name of the file containing the cookie data. The format of the cookie file can be Netscape format, or just pure HTTP header information can be stored in the file. | |
| CURLOPT_COOKIEJAR | A file that saves cookie information after the connection is completed. | |
| CURLOPT_CUSTOMREQUEST | Use a custom request message instead of "GET" or "HEAD" for the HTTP request. This is useful for performing "DELETE" or other more covert HTTP requests. Valid values are "GET" , "POST" , "CONNECT" , etc. That is, don't enter the entire HTTP request here. For example, entering "GET /index.html HTTP/1.0rnrn" is incorrect.
| |
| CURLOPT_EGDSOCKET | Similar to CURLOPT_RANDOM_FILE , except for an Entropy Gathering Daemon socket. | |
| CURLOPT_ENCODING | The value of "Accept-Encoding: " in the HTTP request header. Supported encodings are "identity" , "deflate" and "gzip" . If it is the empty string "" , all supported encoding types will be sent in the request header. | Added in cURL 7.10. |
| CURLOPT_FTPPORT | This value will be used to obtain the IP address required for the FTP "POST" command. The "POST" command tells the remote server to connect to the IP address we specified. This string can be a plain text IP address, a hostname, a network interface name (under UNIX) or just a '-' to use the default IP address. | |
| CURLOPT_INTERFACE | The network sending interface name can be an interface name, IP address or a host name. | |
| CURLOPT_KRB4LEVEL | KRB4 (Kerberos 4) security level. Any of the following values are valid (in order from lowest to highest): "clear" , "safe" , "confidential" , "private". . If the string matches none of these, "private" will be used. Setting this option to NULL will disable KRB4 security authentication. Currently KRB4 security certification can only be used for FTP transfers. | |
| CURLOPT_POSTFIELDS | All data is sent using the "POST" operation in the HTTP protocol. To send a file, prefix the file name with @ and use the full path. This parameter can be passed as a urlencoded string like ' para1=val1¶2=val2&... ' or use an array with the field name as the key and the field data as the value. If value is an array, the Content-Type header will be set to multipart/form-data . | |
| CURLOPT_PROXY | HTTP proxy channel. | |
| CURLOPT_PROXYUSERPWD | A string in the format "[username]:[password]" used to connect to the proxy. | |
| CURLOPT_RANDOM_FILE | The name of a file used to generate the SSL random number seed. | |
| CURLOPT_RANGE | In the form of "XY" , where X and Y are optional options to obtain the range of data, in bytes. The HTTP transport thread also supports several such duplicates separated by commas such as "XY,NM" . | |
| CURLOPT_REFERER | The content of "Referer: " in the HTTP request header. | |
| CURLOPT_SSL_CIPHER_LIST | A list of SSL encryption algorithms. For example RC4-SHA and TLSv1 are both available encryption lists. | |
| CURLOPT_SSLCERT | The name of a file containing a certificate in PEM format. | |
| CURLOPT_SSLCERTPASSWD | Password required for using CURLOPT_SSLCERT certificate. | |
| CURLOPT_SSLCERTTYPE | The type of certificate. Supported formats are "PEM" (default), "DER" and "ENG" . | Added in cURL 7.9.3. |
| CURLOPT_SSLENGINE | Crypto engine variable used for the SSL private key specified in CURLOPT_SSLKEY . | |
| CURLOPT_SSLENGINE_DEFAULT | Variables used for asymmetric encryption operations. | |
| CURLOPT_SSLKEY | The name of the file containing the SSL private key. | |
| CURLOPT_SSLKEYPASSWD | The password for the SSL private key specified in CURLOPT_SSLKEY .
| |
| CURLOPT_SSLKEYTYPE | The encryption type of the private key specified in CURLOPT_SSLKEY . The supported key types are "PEM" (default value), "DER" and "ENG" . | |
| CURLOPT_URL | The URL address that needs to be obtained can also be set in the curl_init() function. | |
| CURLOPT_USERAGENT | Include a "User-Agent:" header string in the HTTP request. | |
| CURLOPT_USERPWD | Pass the username and password required for a connection in the format: "[username]:[password]" . |
For the optional parameters of the following options, value should be set to an array:
| Options | Optional value | Remark |
|---|---|---|
| CURLOPT_HTTP200ALIASES | 200 response code array, the response in the array is considered a correct response, otherwise it is considered an error. | Added in cURL 7.10.3. |
| CURLOPT_HTTPHEADER | An array used to set HTTP header fields. Use an array in the following form to set: array('Content-type: text/plain', 'Content-length: 100') | |
| CURLOPT_POSTQUOTE | A set of FTP commands executed on the server after the FTP request is executed. | |
| CURLOPT_QUOTE | A set of FTP commands to be executed on the server prior to the FTP request. |
For the optional parameters of the following options, value should be set to a stream resource (for example, using fopen()):
| Options | Optional value |
|---|---|
| CURLOPT_FILE | Set the location of the output file. The value is a resource type. The default is STDOUT (browser). |
| CURLOPT_INFILE | The file address that needs to be read when uploading a file. The value is a resource type. |
| CURLOPT_STDERR | Set an error output address, the value is a resource type, replacing the default STDERR . |
| CURLOPT_WRITEHEADER | Set the file address where the header part content is written, and the value is a resource type. |
For the optional parameters of the following options, value should be set to a callback function name:
| Options | Optional value |
|---|---|
| CURLOPT_HEADERFUNCTION | Set a callback function. This function has two parameters. The first is the cURL resource handle, and the second is the output header data. The output of header data must rely on this function, which returns the size of the written data. |
| CURLOPT_PASSWDFUNCTION | Set a callback function with three parameters. The first is the cURL resource handle, the second is a password prompt, and the third parameter is the maximum allowed password length. Returns the value of the password. |
| CURLOPT_PROGRESSFUNCTION | Set up a callback function with three parameters. The first is the cURL resource handle, the second is a file descriptor resource, and the third is the length. Returns the contained data. |
| CURLOPT_READFUNCTION | Callback function name. This function should accept three parameters. The first is the cURL resource; the second is the stream resource passed to cURL through the option CURLOPT_INFILE ; the third parameter is the maximum amount of data that can be read. The callback function must return a string whose length is less than or equal to the requested amount of data (third parameter). Generally read from the incoming stream resource. Returns the empty string as an EOF (end of file) signal. |
| CURLOPT_WRITEFUNCTION | Callback function name. This function should accept two parameters. The first is the cURL resource; the second is the data string to be written. Data must be saved within the function. The function must return the exact number of bytes passed in to write the data, otherwise the transfer will be interrupted by an error. |
Returns TRUE on success, or FALSE on failure.
| Version | illustrate |
|---|---|
| 5.2.10 | Introduced CURLOPT_PROTOCOLS , and CURLOPT_REDIR_PROTOCOLS . |
| 5.1.0 | Introduced CURLOPT_AUTOREFERER , CURLOPT_BINARYTRANSFER , CURLOPT_FTPSSLAUTH , CURLOPT_PROXYAUTH , and CURLOPT_TIMECONDITION . |
| 5.0.0 | Introduced CURLOPT_FTP_USE_EPRT , CURLOPT_NOSIGNAL , CURLOPT_UNRESTRICTED_AUTH , CURLOPT_BUFFERSIZE , CURLOPT_HTTPAUTH , CURLOPT_PROXYPORT , CURLOPT_PROXYTYPE , CURLOPT_SSLCERTTYPE , and CURLOPT_HTTP200ALIASES . |
Initialize a new cURL session and get a web page
<?php// Create a new cURL resource $ch = curl_init();// Set the URL and corresponding options curl_setopt($ch, CURLOPT_URL, "http://www.example.com/"); curl_setopt($ch , CURLOPT_HEADER, false);// Grab the URL and pass it to the browser curl_exec($ch);//Close the cURL resource and release the system resource curl_close($ch);?>
Upload file example:
<?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);?>The output results of the above example are as follows:
Array( [name] => Foo)Array( [file] => Array ( [name] => test.png [type] => image/png [tmp_name] => /tmp/phpcpjNeQ [error] => 0 [ size] => 279 ))
When passing an array to CURLOPT_POSTFIELDS, cURL will encode the data into multipart/form-data, whereas when passing a URL-encoded string, the data will be encoded into application/x-www-form-urlencoded.