YouTip

[ PHP cURL Reference Manual](#) (PHP 4 >= 4.0.2, PHP 5) curl_setopt — Set an option for a cURL transfer. * * * ## Description bool curl_setopt ( resource $ch , int $option , mixed $value ) Sets an option for a cURL session identified by the $ch parameter. * * * ## Parameters **ch** The cURL handle returned by curl_init(). **option** The CURLOPT_XXX option to set. **value** The value to set for the option. For the following options, the value should be set to a boolean: | Option | Possible _value_ | Notes | | --- | --- | --- | | **CURLOPT_AUTOREFERER** | When enabled, automatically sets the _Referer:_ field in the header when following redirects based on the _Location:_ header. | | | **CURLOPT_BINARYTRANSFER** | When enabled, returns the raw output when **CURLOPT_RETURNTRANSFER** is enabled. | | | **CURLOPT_COOKIESESSION** | When enabled, curl will only send a session cookie, ignoring other cookies. By default, cURL will return all cookies to the server. Session cookies are those used to determine if the server-side session is valid. | | | **CURLOPT_CRLF** | When enabled, converts Unix newlines to Windows-style carriage return linefeeds. | | | **CURLOPT_DNS_USE_GLOBAL_CACHE** | When enabled, enables a global DNS cache. This is thread-safe and enabled by default. | | | **CURLOPT_FAILONERROR** | Displays the HTTP status code. The default behavior is to ignore HTTP status codes less than or equal to 400. | | | **CURLOPT_FILETIME** | When enabled, attempts to retrieve the modification time of the remote document. The result is returned via the _CURLINFO_FILETIME_ option of curl_getinfo(). | | | **CURLOPT_FOLLOWLOCATION** | When enabled, recursively returns the _"Location: "_ header from the server back to the server in the header. Use **CURLOPT_MAXREDIRS** to limit the number of redirects. | | | **CURLOPT_FORBID_REUSE** | Forces the connection to close after the transfer, preventing reuse. | | | **CURLOPT_FRESH_CONNECT** | Forces a new connection to be used instead of a cached one. | | | **CURLOPT_FTP_USE_EPRT** | When enabled, uses the EPRT (or LPRT) command for FTP downloads. Set to **FALSE** to disable EPRT and LPRT, using only the PORT command. | | | **CURLOPT_FTP_USE_EPSV** | When enabled, attempts the EPSV command first before reverting to PASV mode during FTP transfers. Set to **FALSE** to disable the EPSV command. | | | **CURLOPT_FTPAPPEND** | When enabled, appends to the file instead of overwriting it. | | | **CURLOPT_FTPASCII** | Alias for **CURLOPT_TRANSFERTEXT**. | | | **CURLOPT_FTPLISTONLY** | When enabled, lists only the names of FTP directories. | | | **CURLOPT_HEADER** | When enabled, includes the header in the output. | | | **CURLINFO_HEADER_OUT** | When enabled, tracks the request string of the handle. | Available since PHP 5.1.3. The **CURLINFO_** prefix is intentional. | | **CURLOPT_HTTPGET** | When enabled, sets the HTTP method to GET. Since GET is the default, this is only used when the method is changed. | | | **CURLOPT_HTTPPROXYTUNNEL** | When enabled, tunnels the transfer through an HTTP proxy. | | | **CURLOPT_MUTE** | When enabled, reverts all modified parameters in cURL functions to their default values. | | | **CURLOPT_NETRC** | After the connection is established, accesses the ~/.netrc file to obtain username and password information for connecting to the remote site. | | | **CURLOPT_NOBODY** | When enabled, excludes the BODY part of the HTML output. | | | **CURLOPT_NOPROGRESS** | When enabled, disables the progress meter for cURL transfers. The default setting is enabled. > **Note**: > > > PHP automatically sets this option to **TRUE**. This option should only be changed for debugging purposes. | | | **CURLOPT_NOSIGNAL** | When enabled, ignores all signals passed from cURL to PHP. This is enabled by default in SAPI multi-threaded transfers. | Added in cURL 7.10. | | **CURLOPT_POST** | When enabled, sends a regular POST request with a type of _application/x-www-form-urlencoded_, similar to form submission. | | | **CURLOPT_PUT** | When enabled, allows HTTP file uploads. Must be set along with **CURLOPT_INFILE** and **CURLOPT_INFILESIZE**. | | | **CURLOPT_RETURNTRANSFER** | Returns the output of curl_exec() as a file stream instead of directly outputting it. | | | **CURLOPT_SSL_VERIFYPEER** | When disabled, cURL stops verifying the server's certificate. Use **CURLOPT_CAINFO** to set the certificate and **CURLOPT_CAPATH** to set the certificate directory. If **CURLOPT_SSL_VERIFYPEER** (default is 2) is enabled, **CURLOPT_SSL_VERIFYHOST** must be set to **TRUE**, otherwise set to **FALSE**. | Defaults to **TRUE** since cURL 7.10. Bundled installation starts from cURL 7.10. | | **CURLOPT_TRANSFERTEXT** | When enabled, uses ASCII mode for FTP transfers. For LDAP, it retrieves plain text information instead of HTML. On Windows systems, _STDOUT_ is not set to binary mode. | | | **CURLOPT_UNRESTRICTED_AUTH** | Continues to append username and password information in the header across multiple locations generated by **CURLOPT_FOLLOWLOCATION**, even if the domain changes. | | | **CURLOPT_UPLOAD** | When enabled, allows file uploads. | | | **CURLOPT_VERBOSE** | When enabled, reports all information, stored in _STDERR_ or the specified **CURLOPT_STDERR**. | | For the following options, the value should be set to an integer: | Option | Possible _value_ | Notes | | --- | --- | --- | | **CURLOPT_BUFFERSIZE** | The size of the buffer to read data into for each transfer, 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 CURLCLOSEPOLICY options, but cURL does not support them yet. | | | **CURLOPT_CONNECTTIMEOUT** | The time in seconds to wait while trying to connect. Use 0 to wait indefinitely. | | | **CURLOPT_CONNECTTIMEOUT_MS** | The time in milliseconds to wait while trying to connect. Use 0 to wait indefinitely. | Added in cURL 7.16.2. Available since PHP 5.2.3. | | **CURLOPT_DNS_CACHE_TIMEOUT** | The time in seconds to keep 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). | Added in cURL 7.12.2. | | **CURLOPT_HTTP_VERSION** | _CURL_HTTP_VERSION_NONE_ (default, let cURL decide), _CURL_HTTP_VERSION_1_0_ (force HTTP/1.0), or _CURL_HTTP_VERSION_1_1_ (force HTTP/1.1). | | | **CURLOPT_INFILESIZE** | The size limit of the file to be uploaded, in bytes. | | | **CURLOPT_LOW_SPEED_LIMIT** | When the transfer speed is less than **CURLOPT_LOW_SPEED_LIMIT** (bytes/sec), PHP will determine if the transfer is too slow based on **CURLOPT_LOW_SPEED_TIME**. | | | **CURLOPT_LOW_SPEED_TIME** | When the transfer speed is less than **CURLOPT_LOW_SPEED_LIMIT** (bytes/sec), PHP will determine if the transfer is too slow based on **CURLOPT_LOW_SPEED_TIME**. | | | **CURLOPT_MAXCONNECTS** | The maximum number of connections allowed. When exceeded, connections to stop are determined by **CURLOPT_CLOSEPOLICY**. | | | **CURLOPT_MAXREDIRS** | The maximum number of HTTP redirects to follow. This option is used with **CURLOPT_FOLLOWLOCATION**. | | | **CURLOPT_PORT** | Specifies the port to connect to. (Optional) | | | **CURLOPT_PROTOCOLS** | A bitmask of **CURLPROTO_***. If enabled, the bitmask limits the protocols libcurl can use during transfer. This allows you to compile libcurl with support for many protocols but restrict it to a subset. By default, libcurl will use all supported protocols. See **CURLOPT_REDIR_PROTOCOLS**. Available protocol options: 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** | A bitmask of **CURLPROTO_***. If enabled, the bitmask limits the protocols libcurl can use during transfer. This allows you to compile libcurl with support for many protocols but restrict it to a subset. By default, libcurl will use all supported protocols. See **CURLOPT_REDIR_PROTOCOLS**. Available protocol options: 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** | The authentication method for the HTTP proxy. Use the bitmask flags from **CURLOPT_HTTPAUTH** to set the appropriate option. 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** | A bitmask of **CURLPROTO_***. If enabled, the bitmask limits the protocols the transfer thread can use when following a redirect with **CURLOPT_FOLLOWLOCATION** enabled. This allows you to restrict the transfer thread to a subset of allowed protocols during redirects. By default, libcurl will allow all protocols except FILE and SCP. This differs slightly from the unconditional following of all supported protocols in the 7.19.4 pre-release version. For protocol constants, refer to **CURLOPT_PROTOCOLS**. | Added in cURL 7.19.4. | | **CURLOPT_RESUME_FROM** | Pass a byte offset to resume the transfer from (for resuming interrupted transfers). | | | **CURLOPT_SSL_VERIFYHOST** | 1: Checks if the server's SSL certificate contains a common name. Translator's note: The common name is generally the domain or subdomain for which you are applying for the SSL certificate. 2: Checks if the common name exists and matches the provided hostname. | | | **CURLOPT_SSLVERSION** | The SSL version to use (2 or 3). By default, PHP will detect this value automatically, although in some cases it needs to be set manually. | | | **CURLOPT_TIMECONDITION** | If the document has been modified since the time specified in **CURLOPT_TIMEVALUE**, returns the page using _CURL_TIMECOND_IFMODSINCE_. If not modified and **CURLOPT_HEADER** is true, returns a _"304 Not Modified"_ header. If **CURLOPT_HEADER** is false, uses _CURL_TIMECOND_IFUNMODSINCE_. The default is _CURL_TIMECOND_IFUNMODSINCE_. | | | **CURLOPT_TIMEOUT** | The maximum number of seconds cURL is allowed to execute. | | | **CURLOPT_TIMEOUT_MS** | The maximum number of milliseconds cURL is allowed to execute. | Added in cURL 7.16.2. Available since PHP 5.2.3. | | **CURLOPT_TIMEVALUE** | Sets a timestamp for **CURLOPT_TIMECONDITION**. By default, _CURL_TIMECOND_IFMODSINCE_ is used. | | For the following options, the value should be set to a string: | Option | Possible _value_ | Notes | | --- | --- | --- | | **CURLOPT_CAINFO** | The filename of a file containing one or more certificates to verify the peer with. This parameter is only meaningful when used with **CURLOPT_SSL_VERIFYPEER**. | | | **CURLOPT_CAPATH** | A directory containing multiple CA certificates. This option is used with **CURLOPT_SSL_VERIFYPEER**. | | | **CURLOPT_COOKIE** | The contents of the _"Cookie: "_ header in the HTTP request. Multiple cookies are separated by a semicolon followed by a space (e.g., _"fruit=apple; colour=red"_). | | | **CURLOPT_COOKIEFILE** | The filename containing cookie data. The cookie file can be in Netscape format or simply HTTP header information saved to a file. | | | **CURLOPT_COOKIEJAR** | The filename to save cookie information to after the connection is closed. | | | **CURLOPT_CUSTOMREQUEST** | Uses a custom request string instead of _"GET"_ or _"HEAD"_ for the HTTP request. This is useful for performing _"DELETE"_ or other less common HTTP requests. Valid values include _"GET"_, _"POST"_, _"CONNECT"_, etc. Do not enter the entire HTTP request here. For example, entering _"GET /index.html HTTP/1.0rnrn"_ is incorrect. > **Note**: > > > Do not use this unless you are sure the server supports this custom request method. | | | **CURLOPT_EGDSOCKET** | Similar to **CURLOPT_RANDOM_FILE**, but for an Entropy Gathering Daemon socket. | | | **CURLOPT_ENCODING** | The value of the _"Accept-Encoding: "_ header in the HTTP request. Supported encodings are _"identity"_, _"deflate"_, and _"gzip"_. If set to an empty string _""_, the request header will send all supported encoding types. | Added in cURL 7.10. | | **CURLOPT_FTPPORT** | This value is used to obtain the IP address for the FTP "POST" command. The "POST" command tells the remote server to connect back to our specified IP address. This string can be a plain text IP address, hostname, a network interface name (on UNIX), or just a '-' to use the default IP address. | | | **CURLOPT_INTERFACE** | The name of the network interface to send from. It can be an interface name, IP address, or hostname. | | | **CURLOPT_KRB4LEVEL** | The KRB4 (Kerberos 4) security level. Any of the following values are valid (from low to high): _"clear"_, _"safe"_, _"confidential"_, _"private"_. If the string does not match any of these, _"private"_ will be used. Setting this option to **NULL** disables KRB4 security authentication. Currently, KRB4 security authentication can only be used for FTP transfers. | | | **CURLOPT_POSTFIELDS** | Sends all data using the HTTP "POST" operation. To send files, prefix the filename with _@_ and use the full path. This parameter can be a URL-encoded string like _'para1=val1&para2=val2&...'_ or an array with field names as keys and field data as values. If _value_ is an array, the _Content-Type_ header will be set to _multipart/form-data_. | | | **CURLOPT_PROXY** | The HTTP proxy tunnel. | | | **CURLOPT_PROXYUSERPWD** | A string in the format _":"_ to connect to the proxy. | | | **CURLOPT_RANDOM_FILE** | The filename used to generate the SSL random seed. | | | **CURLOPT_RANGE** | The range of data to retrieve in the format _"X-Y"_, where X and Y are optional byte offsets. HTTP transfer threads also support multiple such ranges separated by commas, like _"X-Y,N-M"_. | | | **CURLOPT_REFERER** | The contents of the _"Referer: "_ header in the HTTP request. | | | **CURLOPT_SSL_CIPHER_LIST** | A list of SSL ciphers. For example, _RC4-SHA_ and _TLSv1_ are available cipher lists. | | | **CURLOPT_SSLCERT** | The filename of a certificate in PEM format. | | | **CURLOPT_SSLCERTPASSWD** | The password required for the certificate specified by **CURLOPT_SSLCERT**. | | | **CURLOPT_SSLCERTTYPE** | The type of the certificate. Supported formats are _"PEM"_ (default), _"DER"_, and _"ENG"_. | Added in cURL 7.9.3. | | **CURLOPT_SSLENGINE** | The crypto engine variable for the SSL private key specified in **CURLOPT_SSLKEY**. | | | **CURLOPT_SSLENGINE_DEFAULT** | The crypto engine variable for asymmetric encryption operations. | | | **CURLOPT_SSLKEY** | The filename containing the SSL private key. | | | **CURLOPT_SSLKEYPASSWD** | The password for the SSL private key specified in **CURLOPT_SSLKEY**. > **Note**: > > > Since this option contains sensitive password information, ensure the security of this PHP script. | | | **CURLOPT_SSLKEYTYPE** | The type of the private key specified in **CURLOPT_SSLKEY**. Supported key types are _"PEM"_ (default), _"DER"_, and _"ENG"_. | | | **CURLOPT_URL** | The URL to fetch. This can also be set in the curl_init() function. | | | **CURLOPT_USERAGENT** | A string containing the _"User-Agent: "_ header in the HTTP request. | | | **CURLOPT_USERPWD** | A string in the format _":"_ to pass the username and password for the connection. | | For the following options, the value should be set to an array: | Option | Possible _value_ | Notes | | --- | --- | --- | | **CURLOPT_HTTP200ALIASES** | An array of 200 response codes. Responses in this array are considered correct; otherwise, they are considered errors. | Added in cURL 7.10.3. | | **CURLOPT_HTTPHEADER** | An array used to set HTTP header fields. Use an array in the following format: array('Content-type: text/plain', 'Content-length: 100') | | | **CURLOPT_POSTQUOTE** | An array of FTP commands to execute on the server after the FTP request is completed. | | | **CURLOPT_QUOTE** | An array of FTP commands to execute on the server before the FTP request. | | For the following options, the value should be set to a stream resource (e.g., using fopen()): | Option | Possible _value_ | | --- | --- | | **CURLOPT_FILE** | Sets the output file location. The value is a resource type, defaulting to _STDOUT_ (browser). | | **CURLOPT_INFILE** | The file address to read from when uploading files. The value is a resource type. | | **CURLOPT_STDERR** | Sets an error output address. The value is a resource type, replacing the default _STDERR_. | | **CURLOPT_WRITEHEADER** | Sets the file address to write the header portion to. The value is a resource type. | For the following options, the value should be set to a callback function name: | Option | Possible _value_ | | --- | --- | | **CURLOPT_HEADERFUNCTION** | Sets a callback function with two parameters: the first is the cURL resource handle, and the second is the output header data. The header data output must rely on this function, which returns the size of the data written. | | **CURLOPT_PASSWDFUNCTION** | Sets a callback function with three parameters: the first is the cURL resource handle, the second is a password prompt, and the third is the maximum allowed password length. Returns the password value. | | **CURLOPT_PROGRESSFUNCTION** | Sets 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 via the **CURLOPT_INFILE** option; the third is the maximum number of bytes that can be read. The callback function must return a string with a length less than or equal to the requested data amount (the third parameter). Generally, data is read from the incoming stream resource. Return an empty string as the _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. The data must be saved within the function. The function must return the exact number of bytes of the incoming data to be written, otherwise the transfer will be aborted with an error. | * * * ## Return Values Returns TRUE on success, or FALSE on failure. * * * ## Changelog | Version | Description | | --- | --- | | 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`**. | * * * ## Examples Initialize a new cURL session and fetch a webpage <?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