(PHP 4 >= 4.0.2, PHP 5, PHP 7)

curl_setopt — Sets a parameter for the CURL session

List of parameters

cURL handle obtained from curl_init().

Parameter to be set CURLOPT_XXX.

The value of the option parameter.

bool:

Parameter		Notes
CURLOPT_AUTOREFERER	TRUE for automatic field setting Referrer: in requests redirected by header Location:.
CURLOPT_BINARYTRANSFER	TRUE to return the raw response when using a constant CURLOPT_RETURNTRANSFER.	As of PHP 5.1.3 this option is no longer required: raw output is always returned when using the option CURLOPT_RETURNTRANSFER.
CURLOPT_COOKIESESSION	TRUE to instruct the current session to start a new "session" of cookies. This will cause libcurl to ignore any "session" cookies it should have loaded from the previous session. By default, libcurl always saves and loads all cookies, regardless of whether they are "session" or not. "Session" cookies are cookies that do not expire and must only exist for the current "session".
CURLOPT_CERTINFO	TRUE to output SSL certificate information to stream STDERR with secure connections.	Added in cURL 7.19.1. Available starting from PHP 5.3.2. Requires this option to be enabled for correct operation CURLOPT_VERBOSE.
CURLOPT_CONNECT_ONLY	TRUE tells the library to perform the necessary proxy authentication and connection setup, but does not transmit data. This option is implemented for HTTP, SMTP and POP3.	Added in 7.15.2. Available from PHP 5.5.0.
CURLOPT_CRLF	TRUE to convert Unix line endings to CRLF.
CURLOPT_DNS_USE_GLOBAL_CACHE	TRUE to use the global DNS cache. This option is not thread safe and is enabled by default.
CURLOPT_FAILONERROR	TRUE for a detailed report on failure if the received HTTP code is greater than or equal to 400. The default behavior returns the page as normal, ignoring the code.
CURLOPT_FILETIME	TRUE to try to obtain the modification date of a remote document. This value can be obtained using the CURLINFO_FILETIME parameter from the function curl_getinfo().
CURLOPT_FOLLOWLOCATION	TRUE to follow any heading "Location: " sent by the server in its response (note that this happens recursively, PHP will follow any headers sent "Location: ", except when a constant is set CURLOPT_MAXREDIRS).
CURLOPT_FORBID_REUSE	TRUE to force a connection to be closed after its processing has completed so that it cannot be reused.
CURLOPT_FRESH_CONNECT	TRUE to force the use of a new connection instead of a cached one.
CURLOPT_FTP_USE_EPRT	TRUE to use EPRT (and LPRT) for active FTP uploads. Use FALSE in order to disable EPRT and LPRT and use only PORT.
CURLOPT_FTP_USE_EPSV	TRUE for initial testing of the EPSV command during FTP transfers. If the command fails, it will fall back to PASV. Install in FALSE to disable EPSV.
CURLOPT_FTP_CREATE_MISSING_DIRS	TRUE to create missing directories if an FTP operation encounters a non-existent path.
CURLOPT_FTPAPPEND	TRUE to write a remote file to the end, instead of overwriting it over an existing file.
CURLOPT_TCP_NODELAY	Permanently specifies whether the TCP_NODELAY option should be set or cleared (1 = set, 0 = cleared). By default the option is cleared.	Available from PHP 5.2.1 for versions built with libcurl 7.11.2 or later.
CURLOPT_FTPASCII	Nickname CURLOPT_TRANSFERTEXT. Use this instead.
CURLOPT_FTPLISTONLY	TRUE to return only a list of names from the FTP directory.
CURLOPT_HEADER	TRUE to include headers in the output.
CURLINFO_HEADER_OUT	TRUE to track the handle query string.	Available starting from PHP 5.1.3. Prefix CURLINFO_ used specifically.
CURLOPT_HTTPGET	TRUE to reset the HTTP request method to the GET method. Since GET is the default, this parameter is only needed if the request method has previously been changed.
CURLOPT_HTTPPROXYTUNNEL	TRUE to tunnel through the specified HTTP proxy.
CURLOPT_MUTE	TRUE to completely disable cURL function messages.	Removed in cURL 7.15.5 (CURLOPT_RETURNTRANSFER option can be used)
CURLOPT_NETRC	TRUE to read the ~/.netrc file for the login and password for the remote site with which the connection is being established.
CURLOPT_NOBODY	TRUE to exclude the response body from the output. The request method is set to HEAD. Changing this setting to FALSE doesn't change it back to GET.
CURLOPT_NOPROGRESS	TRUE to disable the progress indicator on cURL transfers. Comment: PHP automatically sets this parameter to TRUE, change it only for debugging purposes.
CURLOPT_NOSIGNAL	TRUE to ignore any cURL function that sends signals to the PHP process. This option is enabled by default in multi-threaded SAPIs for correct operation of timeout parameters.
CURLOPT_POST	TRUE to use regular HTTP POST. This POST method uses the normal , commonly used in HTML forms.
CURLOPT_PUT	TRUE to download a file using the HTTP PUT method. The file used must be set using the options CURLOPT_INFILE And CURLOPT_INFILESIZE.
CURLOPT_RETURNTRANSFER	TRUE to return the result of the transfer as a string from curl_exec() instead of direct output to the browser.
CURLOPT_SAFE_UPLOAD	TRUE to disable prefix support @ for downloaded files in CURLOPT_POSTFIELDS, which means that the values ​​passed with @ can be transmitted securely as fields. Instead of a prefix, you can use the option CURLFile d.	Added in PHP 5.5.0 with default value FALSE. In PHP 5.6.0 it became equal to by default TRUE.
CURLOPT_SSL_VERIFYPEER	FALSE to stop cURL from checking the host certificate. Alternative certificates to be verified can be specified using the parameter CURLOPT_CAINFO or the directory with certificates specified by the parameter CURLOPT_CAPATH.	Default is TRUE since cURL version 7.10. The default distribution is installed starting from cURL version 7.10.
CURLOPT_TRANSFERTEXT	TRUE to use ASCII mode for FTP transfers. When using LDAP, the data is returned in plain text instead of HTML. On Windows systems the thread STDOUT does not set to binary mode.
CURLOPT_UNRESTRICTED_AUTH	TRUE to continue sending login and password during redirects (when using CURLOPT_FOLLOWLOCATION), even if the hostname changes.
CURLOPT_UPLOAD	TRUE to prepare for uploading the file to the server.
CURLOPT_VERBOSE	TRUE to display additional information. Writes output to a stream STDERR, or the file specified by the parameter CURLOPT_STDERR.

For the following option parameter values, the value parameter must be of type integer:

Parameter	Set value value	Notes
CURLOPT_BUFFERSIZE	The size of the buffer used for each read. However, there is no guarantee that this request will be completed.	Added in cURL 7.10.
CURLOPT_CLOSEPOLICY	One of the constants CURLCLOSEPOLICY_*. Comment: This option is deprecated as it was never implemented in cURL and did not work.	Removed in PHP 5.6.0.
CURLOPT_CONNECTTIMEOUT	The number of seconds to wait when trying to connect. Use 0 to wait indefinitely.
CURLOPT_CONNECTTIMEOUT_MS	The number of milliseconds to wait when attempting to connect. Use 0 to wait indefinitely. If libcurl is compiled using the system's standard name resolver, then the connection will still use a full second wait as a timeout, with a minimum allowed timeout of 1 second.	Added in cURL version 7.16.2. Available starting from PHP 5.2.3.
CURLOPT_DNS_CACHE_TIMEOUT	The number of seconds that DNS records are stored in memory. By default, this parameter is 120 (2 minutes).
CURLOPT_FTPSSLAUTH	FTP authentication method (in active mode): CURLFTPAUTH_SSL(SSL is checked first), CURLFTPAUTH_TLS(TLS checked first) or CURLFTPAUTH_DEFAULT(cURL decides for itself).	Added in cURL version 7.12.2.
CURLOPT_HTTP_VERSION	CURL_HTTP_VERSION_NONE (by default, CURL chooses which version to use), CURL_HTTP_VERSION_1_0 (force HTTP/1.0), or CURL_HTTP_VERSION_1_1 (force HTTP/1.1).
CURLOPT_HTTPAUTH	You can use the bitwise operator | (or) to combine several methods together. In this case, cURL will poll the server for supported authorization methods and select the best one. CURLAUTH_ANY is an alias CURLAUTH_BASIC | CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM. CURLAUTH_ANYSAFE is an alias CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM.
CURLOPT_INFILESIZE	The expected file size, in bytes, when uploading a file to a remote server. Please note that using this option will not stop further data being sent in excess of this value, as the data sent depends on the result CURLOPT_READFUNCTION.
CURLOPT_LOW_SPEED_LIMIT	Upper threshold for data transfer rate, in bytes per second. The verification takes place within CURLOPT_LOW_SPEED_TIME seconds, after which PHP considers the transfer too slow and aborts it.
CURLOPT_LOW_SPEED_TIME	The maximum number of seconds during which the transfer rate must not exceed CURLOPT_LOW_SPEED_LIMIT, otherwise PHP will mark the transfer as too slow and stop it.
CURLOPT_MAXCONNECTS	Maximum number of persistent connections. When the limit is reached, the parameter is used to determine which connection to close. CURLOPT_CLOSEPOLICY.
CURLOPT_MAXREDIRS	The maximum number of accepted redirects. Use this option together with the option CURLOPT_FOLLOWLOCATION.
CURLOPT_PORT	Alternative connection port.
CURLOPT_POSTREDIR	A bit mask containing 1 (301 Moved Permanently), 2 (302 Found) and 4 (303 See Other) to specify whether the HTTP POST method should be processed when the option is enabled CURLOPT_FOLLOWLOCATION if the specified type of redirection occurred.	Added in cURL 7.19.1. Available since PHP 5.3.2.
CURLOPT_PROTOCOLS	Bit mask of values CURLPROTO_*. This mask limits the protocols used by libcurl. This allows you to have libcurl work with a large number of protocols, and limit the operation of certain transfers to only a subset of them. By default, libcurl uses all supported protocols. See also parameter CURLOPT_REDIR_PROTOCOLS. Correct protocol values: CURLPROTO_HTTP , CURLPROTO_HTTPS , CURLPROTO_FTP , CURLPROTO_FTPS , CURLPROTO_SCP , CURLPROTO_SFTP , CURLPROTO_TELNET , CURLPROTO_LDAP , CURLPROTO_LDAPS , CURLPROTO_DICT , CURLPROTO_FILE , CURLP ROTO_TFTP, CURLPROTO_ALL
CURLOPT_PROXYAUTH	HTTP authorization methods used when connecting to a proxy server. Use the same bit masks that were described for the parameter CURLOPT_HTTPAUTH. Currently, only CURLAUTH_BASIC and CURLAUTH_NTLM are supported for proxy authorization.	Added in cURL version 7.10.7.
CURLOPT_PROXYPORT	The port number of the proxy server to which the connection is made. This number can also be set using the parameter CURLOPT_PROXY.
CURLOPT_PROXYTYPE	Either CURLPROXY_HTTP (default) or CURLPROXY_SOCKS5 .	Added in cURL 7.10.
CURLOPT_REDIR_PROTOCOLS	Bit mask of values CURLPROTO_*. This bitmask limits the protocols used by libcurl when redirecting (with the parameter enabled CURLOPT_FOLLOWLOCATION). This allows you to limit the set of protocols used when redirecting for some transmissions. By default, libcurl supports all protocols except FILE and SCP. In versions prior to 7.19.4, redirection was used for all protocols without exception. See also parameter description CURLOPT_PROTOCOLS for a list of constants with protocol values.	Added in cURL version 7.19.4.
CURLOPT_RESUME_FROM	Transmission start offset, in bytes.
CURLOPT_SSL_VERIFYHOST	Use 1 to check for the existence of a common name in the SSL certificate. Use 2 to check that the common name exists and also matches the specified host. In a combat environment, the value of this parameter should be 2 (set by default).	Support for value 1 has been removed in cURL 7.28.1
CURLOPT_SSLVERSION	One of the constants CURL_SSLVERSION_DEFAULT (0), CURL_SSLVERSION_TLSv1 (1), CURL_SSLVERSION_SSLv2 (2), CURL_SSLVERSION_SSLv3 (3), CURL_SSLVERSION_TLSv1_0 (4), CURL_SSLVERSION_TLSv1_1(5) or CURL_SSLVERSION_TLSv1_2 (6).
CURLOPT_TIMECONDITION	Parameter interpretation method CURLOPT_TIMEVALUE. Use CURL_TIMECOND_IFMODSINCE to return the page only if it has changed since the time specified in the parameter CURLOPT_TIMEVALUE. If the page has not been modified, the title will be returned "304 Not Modified", implying that the parameter CURLOPT_HEADER installed in TRUE. Use CURL_TIMECOND_IFUNMODSINCE for the opposite effect. The default is CURL_TIMECOND_IFMODSINCE.
CURLOPT_TIMEOUT	The maximum number of seconds allowed for executing cURL functions.
CURLOPT_TIMEOUT_MS	The maximum number of milliseconds allowed for executing cURL functions. If libcurl is built using the normal system name resolver, then this connection span will still use second rounding timeouts, with a minimum timeout allowed of one second.	Added in cURL version 7.16.2. Available starting from PHP 5.2.3.
CURLOPT_TIMEVALUE	Number of seconds since January 1, 1970. This time will be used by the parameter CURLOPT_TIMECONDITION. By default, the CURL_TIMECOND_IFMODSINCE parameter is used.
CURLOPT_MAX_RECV_SPEED_LARGE	If the download speed exceeds this value (specified in bytes per second) on average over the entire transfer, the download will be paused to maintain the average speed less than or equal to this parameter. By default, the speed is not limited.
CURLOPT_MAX_SEND_SPEED_LARGE	If the upload to the server exceeds this value (specified in bytes per second) on average throughout the entire transfer, the upload will be paused to maintain an average speed less than or equal to this parameter. By default, the speed is not limited.	Added in cURL 7.15.5. Available starting from PHP 5.4.0.
CURLOPT_SSH_AUTH_TYPES	A bitmask consisting of one or more constants: CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD. Install CURLSSH_AUTH_ANY in order for libcurl to choose one of them independently.	Added in cURL 7.16.1.
CURLOPT_IPRESOLVE	Allows an application to select the type of IP address with which the hostname is determined. This is necessary if you are using a hostname that is derived from more than one version of the IP address. Possible values ​​could be CURL_IPRESOLVE_WHATEVER, CURL_IPRESOLVE_V4, CURL_IPRESOLVE_V6, and by default CURL_IPRESOLVE_WHATEVER.	Added in cURL 7.10.8.

For the following option parameter values, the value parameter must be of type string:

Parameter	Set value value	Notes
CURLOPT_CAINFO	The name of a file containing one or more certificates against which nodes will be checked. This parameter only makes sense when used in conjunction with CURLOPT_SSL_VERIFYPEER.	Requires an absolute path.
CURLOPT_CAPATH	A directory containing several CA certificates. Use this option in conjunction with CURLOPT_SSL_VERIFYPEER.
CURLOPT_COOKIE	Header content "Cookie:", used in the HTTP request. Please note that 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 cookies. This file must be in Netscape format or simply HTTP headers written to the file. If an empty string is passed as the file name, then cookies will not be saved, but their processing will still be enabled.
CURLOPT_COOKIEJAR	The name of the file in which all internal cookies of the current transfer will be saved after the handle is closed, for example after calling curl_close.
CURLOPT_CUSTOMREQUEST	Custom request method used instead "GET" or "HEAD" when making an HTTP request. This is useful for queries "DELETE" or other, more rare HTTP requests. Correct meanings would be words like "GET", "POST", "CONNECT" and so on; those. Do not enter the entire HTTP request line here. For example, an indication "GET /index.html HTTP/1.0\r\n\r\n" will be wrong. Comment: Do not use this feature until you are sure that the server supports this type of request.
CURLOPT_EGDSOCKET	Like CURLOPT_RANDOM_FILE, except that the filename is set to the Entropy Gathering Daemon socket.
CURLOPT_ENCODING	Header content "Accept-Encoding: ". This allows the request to be decoded. Supported encodings are "identity", "deflate" And "gzip". If an empty string is passed, "" , a header containing all supported encoding types is sent.	Added in cURL 7.10.
CURLOPT_FTPPORT	The value that will be used to determine the IP address for the FTP "PORT" command. The "PORT" command tells the server which IP address it should connect to. This can be an IP address, hostname, network interface name (under Unix), or simply "-" to use the default system IP address.
CURLOPT_INTERFACE	The name of the network interface to use. Can be an interface name, an IP address, or a host name.
CURLOPT_KEYPASSWD	Password required to use the private key CURLOPT_SSLKEY or CURLOPT_SSH_PRIVATE_KEYFILE.	Added in cURL 7.16.1.
CURLOPT_KRB4LEVEL	Security level KRB4 (Kerberos 4). Any of the following values ​​(in order from weakest to strongest) are correct: "clear", "safe", "confidential", "private".. If the specified string differs from the given values, the value will be used "private". Setting this option to NULL will completely disable KRB4 security. At the moment, KRB4 security only works with FTP transactions.
CURLOPT_POSTFIELDS	All data transmitted in an HTTP POST request. To transfer a file, specify before the file name @ , and also use the full path to the file. The file type can also be specified using the format " ;type=mimetype" following the file name. This parameter can be passed as a url-encoded string, like " para1=val1¶2=val2&...", and in the form of an array, the keys of which will be the names of the fields, and the values ​​will be their contents. If value is an array, the header Content-Type will be set to multipart/form-data. Starting from PHP 5.2.0, when transferring files with the prefix @ , value must be an array. Since PHP 5.5.0, prefix @ is deprecated and files can be sent using CURLFile. Prefix @ can be disabled to allow values ​​starting with @ by setting the option CURLOPT_SAFE_UPLOAD in meaning TRUE.
CURLOPT_PROXY	HTTP proxy through which requests will be routed.
CURLOPT_PROXYUSERPWD	Login and password written in the form ":" , used when connecting through a proxy.
CURLOPT_RANDOM_FILE	The name of the file used to initialize the random number generator for SSL.
CURLOPT_RANGE	Range of data to be downloaded, in format "X-Y", and either X or Y can be omitted. The HTTP protocol also supports the transmission of multiple ranges separated by commas, they are specified in the format "X-Y,N-M".
CURLOPT_REFERER	Header content "Referrer:", which will be used in the HTTP request.
CURLOPT_SSH_HOST_PUBLIC_KEY_MD5	A string containing 32 hexadecimal digits. The string must be an MD5 checksum of the remote computer's public key, and libcurl will reset the connection to the remote host until the checksum matches the public key. This option is only for transferring data using SCP and SFTP.	Added in cURL 7.17.1.
CURLOPT_SSH_PUBLIC_KEYFILE	The file name for your public key. If not specified, libcurl defaults to the file $HOME/.ssh/id_dsa.pub if the HOME environment variable is set and the file "id_dsa.pub" in the current directory if the HOME environment variable is not set.	Added in cURL 7.16.1.
CURLOPT_SSH_PRIVATE_KEYFILE	The file name for your private key. If not specified, libcurl defaults to the $HOME/.ssh/id_dsa file if the HOME environment variable is set and the "id_dsa" file in the current directory if the HOME environment variable is not set. If the file is password protected, set the password using CURLOPT_KEYPASSWD.	Added in cURL 7.16.1.
CURLOPT_SSL_CIPHER_LIST	List of ciphers used in SSL transfers. For example, RC4-SHA And TLSv1 are valid cipher lists.
CURLOPT_SSLCERT	The name of a file with a correctly formatted PEM certificate.
CURLOPT_SSLCERTPASSWD	Password required to use the certificate CURLOPT_SSLCERT.
CURLOPT_SSLCERTTYPE	Certificate format. Formats supported "PEM"(default), "DER" And "ENG".	Added in cURL version 7.9.3.
CURLOPT_SSLENGINE	The encryption engine ID for the SSL private key specified in the parameter CURLOPT_SSLKEY.
CURLOPT_SSLENGINE_DEFAULT	The identifier of the encryption mechanism used for asymmetric encryption operations.
CURLOPT_SSLKEY	The name of the SSL private key file.
CURLOPT_SSLKEYPASSWD	The secret password required to use the SSL private key specified by the parameter CURLOPT_SSLKEY. Comment: Since this parameter contains a valuable password, remember to keep this PHP script in a safe place.
CURLOPT_SSLKEYTYPE	The type of SSL private key specified in the parameter CURLOPT_SSLKEY. The following key types are supported: "PEM"(default), "DER" And "ENG".
CURLOPT_URL	Downloadable URL. This parameter can also be set when initializing a session using curl_init().
CURLOPT_USERAGENT	Header content "User-Agent: ", sent in an HTTP request.
CURLOPT_USERPWD	Login and password used during connection, specified in the format ":" .

For the following option parameter values, the value parameter must be an array:

Parameter	Set value value	Notes
CURLOPT_HTTP200ALIASES	An array of HTTP 200 responses that will be treated as correct responses rather than erroneous ones.	Added in cURL version 7.10.3.
CURLOPT_HTTPHEADER	An array of set HTTP headers, in the format array("Content-type: text/plain", "Content-length: 100")
CURLOPT_POSTQUOTE	An array of FTP commands executed on the server after an FTP request is completed.
CURLOPT_QUOTE	An array of FTP commands executed on the server before making an FTP request.

For the following option parameter values, the value parameter must be a stream handle (returned, for example, by the function fopen()):

Parameter	Set value value
CURLOPT_FILE	The file in which the transfer result will be written. Default output stream STDOUT(browser window).
CURLOPT_INFILE	The file from which data should be read when uploaded to the server.
CURLOPT_STDERR	Alternative error output file used in place of the error stream STDERR.
CURLOPT_WRITEHEADER	The file in which the headers of the current operation will be written.

For the following option parameter values, the value parameter must be a valid function name or closure:

Parameter	Set value value
CURLOPT_HEADERFUNCTION	The callback function takes two parameters. The first parameter is the cURL handle, the second parameter is a string containing the headers to be written. Headers must be written using this callback function. Should return the number of bytes written.
CURLOPT_PASSWDFUNCTION	The callback function takes three parameters. The first parameter is the cURL handle, the second parameter is the password prompt string, and the third parameter is the maximum password length. Should return a string containing the password.
CURLOPT_PROGRESSFUNCTION	The callback function takes five parameters. The first is the cURL descriptor, the second is the total number of bytes expected to be downloaded from the server, the third is the number of bytes already downloaded, the fourth is the total number of bytes expected to be sent to the server, and the fifth is the number of bytes already sent. Comment: The callback function is called only if the option CURLOPT_NOPROGRESS set to value FALSE. You can return a non-zero value to cancel the transfer. In this case an error will be displayed CURLE_ABORTED_BY_CALLBACK.
CURLOPT_READFUNCTION	The callback function takes three parameters. The first parameter is the cURL handle, the second parameter is the stream resource passed to cURL via the option CURLOPT_INFILE, and the third parameter is the maximum allowed amount of data to be read. The callback function must return a string of length no greater than the requested amount of data, usually by reading from the passed streaming resource. Should return an empty string to signal the end of the file EOF.
CURLOPT_WRITEFUNCTION	The callback function takes two parameters. The first parameter is the cURL handle, and the second parameter is the string containing the data to be written. Data must be saved using this function. It must return the exact number of bytes written, otherwise the download will be aborted with an error.

Other meanings:

Return values

Returns TRUE upon successful completion or FALSE in case of an error.

List of changes

Version	Description
5.6.0	Option CURL_SAFE_UPLOAD now has a default value of TRUE.
5.6.0	Removed option CURLOPT_CLOSEPOLICY and its associated meanings.
5.5.0	The cURL resource is added as the first argument to the callback function CURLOPT_PROGRESSFUNCTION.
5.5.0	Added option CURLOPT_SHARE.
5.3.0	Added option CURLOPT_PROGRESSFUNCTION.
5.2.10	Added options CURLOPT_PROTOCOLS And CURLOPT_REDIR_PROTOCOLS.
5.1.0	Added options CURLOPT_AUTOREFERER, CURLOPT_BINARYTRANSFER, CURLOPT_FTPSSLAUTH, CURLOPT_PROXYAUTH And CURLOPT_TIMECONDITION.
5.0.0	Added options CURLOPT_FTP_USE_EPRT, CURLOPT_NOSIGNAL, CURLOPT_UNRESTRICTED_AUTH, CURLOPT_BUFFERSIZE, CURLOPT_HTTPAUTH, CURLOPT_PROXYPORT, CURLOPT_PROXYTYPE, CURLOPT_SSLCERTTYPE And CURLOPT_HTTP200ALIASES.

Examples

Example #1 Initializing a CURL session and loading a web page

// create a new cURL resource
$ch = curl_init();

/* 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 result of running this example:

Array ( => Foo) Array ( => Array ( => test.png => image/png => /tmp/phpcpjNeQ => 0 => 279))

Notes

Comment:

Passing an array to CURLOPT_POSTFIELDS encodes the data as multipart/form-data, whereas passing a URL-encoded string will encode the data as application/x-www-form-urlencoded.

cURL is a tool that allows you to interact with various servers and supports many protocols: HTTP, FTP, TELNET, etc. cURL is originally a command line utility. But, fortunately for us, PHP supports working with the cURL library. In this article we will look at non-trivial examples of working with cURL.

Why cURL?

In fact, there are many other ways to send a request to another server to, for example, retrieve the content of a page. Many people, mostly out of laziness, use simple PHP functions instead of cURL:

$content = file_get_contents("http://www.example.com"); // or $lines = file("http://www.example.com"); // or readfile("http://www.example.com");

However, they do not allow for efficient error handling. There are also a number of tasks that they cannot do at all - for example, working with cookies, authorization, post requests, downloading files.

cUrl is a powerful tool that supports multiple protocols and provides complete request information.

cUrl Basics

Before moving on to complex examples, let's look at the basic structure of a cURL request in PHP. To perform a cURL request in PHP, you need to take 4 main steps:

1. Initialization.
2. Setting options.
3. Executing the request.
4. Cleaning resources.

// 1. initialization $ch = curl_init(); // 2. set options, including URL curl_setopt($ch, CURLOPT_URL, "http://www.google.com"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_HEADER, 0); // 3. executing the request and receiving the response $output = curl_exec($ch); // 4. cleaning resources curl_close($ch);

We'll mostly be looking at step #2 in this article since that's where the magic happens. The list of cURL options is very large, so we will not consider all the options today, but will use those that are useful for solving specific problems.

Bug tracking

If necessary, you can add the following lines to track errors:

// ... $output = curl_exec($ch); if ($output === FALSE) ( echo "cURL Error: " . curl_error($ch); ) // ...

Please note that we use “===” instead of “==” because It is necessary to distinguish between an empty server response and the Boolean value FALSE, which is returned in case of an error.

Getting information about a request

Another optional step is to obtain information about the cURL request after it has been executed.

// ... curl_exec($ch); $info = curl_getinfo($ch); echo "Took " . $info["total_time"] . "seconds for url". $info["url"]; // ...

As a result, you will receive an array with the following information:

• "url"
• "content_type"
• "http_code"
• "header_size"
• "request_size"
• "filetime"
• "ssl_verify_result"
• "redirect_count"
• "total_time"
• "namelookup_time"
• "connect_time"
• "pretransfer_time"
• "size_upload"
• "size_download"
• "speed_download"
• "speed_upload"
• "download_content_length"
• "upload_content_length"
• "starttransfer_time"
• "redirect_time"

Redirect tracking, depending on the browser

In this example, we will write a script that will detect redirects based on different browser settings. For example, some sites redirect visitors from mobile devices to visitors from other countries.

We'll use the CURLOPT_HTTPHEADER option to set our own headers, including User-Agent and Language, and see where sites redirect us.

// URLs $urls = array("http://www.cnn.com", "http://www.mozilla.com", "http://www.facebook.com"); // browsers $browsers = array("standard" => array ("user_agent" => "Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.1.6) Gecko/20091201 Firefox/3.5. 6 (.NET CLR 3.5.30729)", "language" => "en-us,en;q=0.5"), "iphone" => array ("user_agent" => "Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) Version/3.0 Mobile/1A537a Safari/419.3", "language" => "en"), "french" => array ("user_agent" = > "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; GTB6; .NET CLR 2.0.50727)", "language" => "fr,fr-FR;q=0.5")); foreach ($urls as $url) ( echo "URL: $url\n"; foreach ($browsers as $test_name => $browser) ( $ch = curl_init(); // set the address curl_setopt($ch, CURLOPT_URL, $url); // indicate the browser and language used curl_setopt($ch, CURLOPT_HTTPHEADER, array("User-Agent: ($browser["user_agent"])", "Accept-Language: ($browser["language"]) ")); // we don't need the contents of the page curl_setopt($ch, CURLOPT_NOBODY, 1); // we only need headers curl_setopt($ch, CURLOPT_HEADER, 1); // return the result instead of its output curl_setopt($ch, CURLOPT_RETURNTRANSFER , 1); $output = curl_exec($ch); curl_close($ch); // define redirections in HTTP headers? if (preg_match("!Location: (.*)!", $output, $matches)) ( echo "$test_name: redirects to $matches\n"; ) else ( echo "$test_name: no redirection\n"; ) ) echo "\n\n"; )

In a loop we check browsers for each URL. First we set the options for our request: URL and browser and language to be tested.

Because We have set a special option; the result of the request will contain only HTTP headers. Using a simple regular expression, we can check if the response contains the string "Location:".

Result of script execution:

URL: http://www.cnn.com standard: redirects to http://edition.cnn.com/ iphone: redirects to http://edition.cnn.com/ French: redirects to http://edition.cnn .com/ URL: http://www.mozilla.com standard: redirects to https://www.mozilla.org/firefox/ iphone: redirects to https://www.mozilla.org/firefox/ french: redirects to https://www.mozilla.org/firefox/ URL: http://www.facebook.com standard: redirects to https://www.facebook.com/ iphone: redirects to http://m.facebook.com /?refsrc=http%3A%2F%2Fwww.facebook.com%2F&_rdr French: no redirection

Sending POST requests

When performing GET requests, data can be passed in the query string. For example, when you search on Google, your query is translated into a URL:

http://www.google.com/search?q=google

To get the result of this query you don't even need cURL, you can be lazy and use "file_get_contents()".

But some HTML forms use the POST method. In this case, the data is sent in the body of the request message rather than in the URL itself.

Let's write a script that will send POST requests. First, let's create a simple PHP file that will accept these requests and return the data sent to it. Let's call it post_output.php :

$url = "http://localhost/post_output.php"; $post_data = array ("foo" => "bar", "query" => "FooBar", "action" => "Submit"); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // make a POST request curl_setopt($ch, CURLOPT_POST, 1); // add data curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); $output = curl_exec($ch); curl_close($ch); echo $output;

This script will output:

Array ( => bar => FooBar => Submit)

This script sent a POST request to the post_output.php file. which outputted the contents of the $_POST array and we received this response using cURL.

Uploading files

Just like in the previous example, let's create a file that will accept requests, upload_output.php :

Print_r($_FILES);

And the script itself that downloads the files:

$url = "http://localhost/upload_output.php"; $post_data = array ("foo" => "bar", // file to upload "upload" => "@/tmp/desert.jpg"); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); $output = curl_exec($ch); curl_close($ch); echo $output;

If you want to upload a file, all you need to do is pass the path to it, just like a normal POST request parameter, prefixed with "@". The result of the script:

Array ( => Array ( => desert.jpg => application/octet-stream => /tmp/phpAhEvXy => 0 => 845941))

Multi cURL

One of the advanced features of cURL in PHP is the ability to execute multiple requests simultaneously and asynchronously.

Under normal conditions, the script stops and waits for the request to complete. And if you need to execute a lot of queries, it can take a lot of time, because... you will perform sequentially. This limitation can be bypassed:

// create handlers $ch1 = curl_init(); $ch2 = curl_init(); // set options curl_setopt($ch1, CURLOPT_URL, "http://lxr.php.net/"); curl_setopt($ch1, CURLOPT_HEADER, 0); curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/"); curl_setopt($ch2, CURLOPT_HEADER, 0); //create the multiple cURL handle $mh = curl_multi_init(); // add handlers curl_multi_add_handle($mh,$ch1); curl_multi_add_handle($mh,$ch2); $running = null; // execute requests do ( curl_multi_exec($mh, $running); ) while ($running > 0); // free up resources curl_multi_remove_handle($mh, $ch1); curl_multi_remove_handle($mh, $ch2); curl_multi_close($mh);

The idea is that you can create multiple cURL handles, combine them under one multi-handle, and execute them asynchronously.

First, everything is the same as with a regular cURL request - a descriptor is created ( curl_init() ), parameters are set ( curl_setopt() ). Next, a multi-descriptor is created ( curl_multi_init() ) and the previously created regular descriptors are added ( curl_multi_add_handle() ). Instead of calling curl_exec() normally, we will call curl_multi_exec() this function informs us about the number of active connections using the second parameter - $running. Therefore, the loop runs until $running becomes equal to 0. And, of course, after finishing the work, it is necessary to release resources.

In this example, we simply output the result of the queries to STDOUT. Let's consider a non-trivial case of using multi cURL.

Checking External Links in WordPress

Imagine a blog with a lot of posts containing links to external sites. Some of these links may not work.

Let's write a script that will find all broken links and show them to us.

First we need to pull all external links from the database:

// CONFIG $db_host = "localhost"; $db_user = "root"; $db_pass = ""; $db_name = "wordpress"; $excluded_domains = array("localhost", "site"); $max_connections = 10; $url_list = array(); $working_urls = array(); $dead_urls = array(); $not_found_urls = array(); $active = null; // connect to MySQL if (!mysql_connect($db_host, $db_user, $db_pass)) ( die("Could not connect: " . mysql_error()); ) if (!mysql_select_db($db_name)) ( die("Could not select db: " . mysql_error()); ) // take all posts with links in the text $q = "SELECT post_content FROM wp_posts WHERE post_content LIKE "%href=%" AND post_status = "publish" AND post_type = "post" "; $r = mysql_query($q) or die(mysql_error()); while ($d = mysql_fetch_assoc($r)) ( // collect all links using regular expression if (preg_match_all("/href=\"(.*?)\"/", $d["post_content"], $matches )) ( foreach ($matches as $url) ( // filter out unnecessary domains $tmp = parse_url($url); if (isset($tmp["host"]) && in_array($tmp["host"], $ excluded_domains)) ( continue; ) // put together $url_list = $url; ) ) ) // remove repetitions $url_list = array_values(array_unique($url_list)); if (!$url_list) ( die("No URL to check"); )

In this part of the script, we simply pull out all external links from the database. Let's check them:

$mh = curl_multi_init(); // 1. add links for ($i = 0; $i< $max_connections; $i++) { add_url_to_multi_handle($mh, $url_list); } // основной цикл do { curl_multi_exec($mh, $curRunning); // 2. один из потоков завершил работу if ($curRunning != $running) { $mhinfo = curl_multi_info_read($mh); if (is_array($mhinfo) && ($ch = $mhinfo["handle"])) { // 3. один из запросов выполнен, можно получить информацию о нем $info = curl_getinfo($ch); // 4. нерабочая ссылка if (!$info["http_code"]) { $dead_urls = $info["url"]; // 5. 404? } else if ($info["http_code"] == 404) { $not_found_urls = $info["url"]; // 6. верная ссылка } else { $working_urls = $info["url"]; } // 7. удаляем отработавший дескриптор curl_multi_remove_handle($mh, $mhinfo["handle"]); curl_close($mhinfo["handle"]); // 8. добавим новый урл add_url_to_multi_handle($mh, $url_list); $running = $curRunning; } } } while ($curRunning >0); curl_multi_close($mh); echo "==Dead URLs==\n"; echo implode("\n", $dead_urls) . "\n\n"; echo "==404 URLs==\n"; echo implode("\n", $not_found_urls) . "\n\n"; echo "==Working URLs==\n"; echo implode("\n", $working_urls); echo "\n\n"; // 9. adds a handle with the given URL function add_url_to_multi_handle($mh, $url_list) ( static $index = 0; // if there are still links if (isset($url_list[$index])) ( // everything is as usual $ ch = curl_init(); // set options curl_setopt($ch, CURLOPT_URL, $url_list[$index]); // return rather than display the result curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // allow redirects curl_setopt($ ch, CURLOPT_FOLLOWLOCATION, 1); // get only headers to save time curl_setopt($ch, CURLOPT_NOBODY, 1); // add to the multi-handle curl_multi_add_handle($mh, $ch); $index++; ) )

Let's look at the code in more detail (the numbering corresponds to the comments in the code):

1. We add an initial number of descriptors so as not to overload the system with threads. The number is controlled by the $max_connections variable.
2. The $curRunning variable stores the number of running threads, $running stores the previous value; if they become unequal, then one of the threads has completed work.
3. We receive information about the completed request.
4. If there is no response from the server, the link is not working.
5. The server response is 404.
6. Otherwise the link works.
7. The request is completed, we release resources.
8. Let's add a new URL to the multi descriptor.
9. Function add_url_to_multi_handle() adds a new handle with the given URL to the multi-descriptor.

Let's run the script:

Dead URLs== xample1234.com/ ==404 URLs== www.google.com/dsfasdfafd ==Working URLs== ru.php.net/manual/ru/function.time.php www.cssbuttongenerator.com/ csslint. net/ codex.wordpress.org/Plugin_API/Action_Reference fortawesome.github.io/Font-Awesome/ fortawesome.github.io/Font-Awesome/ www.oracle.com/technetwork/java/javafx/downloads/index.html codex. wordpress.org/Plugin_API/Filter_Reference codex.wordpress.org/Roles_and_Capabilities code.google.com/p/google-api-php-client/wiki/OAuth2#Google_APIs_Console jplayer.org/ code.google.com/p/google-api -php-client/ developers.google.com/+/ accounts.google.com/ServiceLogin?service=devconsole&passive=1209600&continue=https%3A%2F%2Fcode.google.com%2Fapis%2Fconsole%2F&followup=https%3A%2F %2Fcode.google.com%2Fapis%2Fconsole%2F daneden.github.io/animate.css/ github.com/daneden/animate.css ru2.php.net/manual/ru/function.autoload.php www.google. com/recaptcha/api/verify phpunit.de/phpunit.de/manual/current/en/phpunit-book.html

The check took about 2 seconds. By running 10 threads simultaneously, performance increases 10 times compared to regular cURL requests. To get the contents of the server response, use the function curl_multi_getcontent($ch) , where $ch is a descriptor obtained from curl_multi_info_read() .

Other cURL features in PHP

HTTP authentication

If the HTTP request requires authentication, use the following code:

$url = "http://www.somesite.com/members/"; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // send username and password curl_setopt($ch, CURLOPT_USERPWD, "myusername:mypassword"); // if redirects are allowed curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1); // cURL will send the password after redirects curl_setopt($ch, CURLOPT_UNRESTRICTED_AUTH, 1); $output = curl_exec($ch); curl_close($ch);

Upload via FTP

PHP has its own library for working with FTP, but you can also use cURL:

// read the file $file = fopen("/path/to/file", "r"); // url already contains the necessary data $url = "ftp://username: [email protected]:21/path/to/new/file"; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // options curl_setopt($ch, CURLOPT_UPLOAD, 1); curl_setopt($ch, CURLOPT_INFILE, $fp); curl_setopt($ch, CURLOPT_INFILESIZE, filesize("/path/to/file")); curl_setopt($ch, CURLOPT_FTPASCII, 1); $output = curl_exec($ ch); curl_close($ch);

Using a proxy

Requests can be made through a specific proxy:

$ch = curl_init(); curl_setopt($ch, CURLOPT_URL,"http://www.example.com"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // proxy address curl_setopt($ch, CURLOPT_PROXY, "11.11.11.11:8080"); // if authorization is required curl_setopt($ch, CURLOPT_PROXYUSERPWD,"user:pass"); $output = curl_exec($ch); curl_close($ch);

Callback functions

It is possible to use callbacks while the request is running, without waiting for it to complete. For example, while the server response is being downloaded, we can use the data already received without waiting for the complete download.

$ch = curl_init(); curl_setopt($ch, CURLOPT_URL,"http://example.com"); curl_setopt($ch, CURLOPT_WRITEFUNCTION,"progress_function"); curl_exec($ch); curl_close($ch); function progress_function($ch,$str) ( echo $str; return strlen($str); )

The callback function must return the length of the string for the request to work correctly.

Each time the next part of the server response is received, a callback will be called.

Conclusion

In this article, we looked at the advanced features of cURL in PHP. Next time you need to make URL requests, use cURL.

We often have to download various files from the Internet, for example, executable program files, script files, source archives. But this does not always need to be done through the browser. In many situations it is much easier to perform all actions through the terminal. Because this way you can automate the process. On the other hand, webmasters from time to time have to test website accessibility, check sent and received headers, and much more.

To solve such problems and problems of a similar range, you can use the curl utility. It allows you to solve a much wider range of problems, including even simulating user actions on the site. In this article we will look at how to use curl, what it is and why this program is needed.

In fact, curl is more than just a command line utility for Linux or Windows. This is a set of libraries that implement the basic capabilities of working with URL pages and transferring files. The library supports working with protocols: FTP, FTPS, HTTP, HTTPS, TFTP, SCP, SFTP, Telnet, DICT, LDAP, as well as POP3, IMAP and SMTP. It is great for simulating user actions on pages and other operations with URLs.

Support for the curl library has been added to many different programming languages ​​and platforms. The curl utility is an independent wrapper for this library. It is this utility that we will focus on in this article.

curl command

Before moving on to a description of how the curl linux command can be used, let's look at the utility itself and its main options that we will need. The syntax of the utility is very simple:

$ curl options link

Now let's look at the main options:

• -# - display a simple progress bar during loading;
• -0 - use the http 1.0 protocol;
• -1 - use the tlsv1 encryption protocol;
• -2 - use sslv2;
• -3 - use sslv3;
• -4 - use ipv4;
• -6 - use ipv6;
• -A- indicate your USER_AGENT;
• -b- save Cookie to a file;
• -c- send Cookie to the server from a file;
• -C- continue downloading the file from the break point or specified offset;
• -m- maximum waiting time for a response from the server;
• -d- send data using the POST method;
• -D- save headers returned by the server to a file;
• -e- set the Referer-uri field, indicating which site the user came from;
• -E- use an external SSL certificate;
• -f- do not display error messages;
• -F- send data in the form of a form;
• -G- if this option is enabled, then all data specified in the -d option will be transmitted using the GET method;
• -H- transfer headers to the server;
• -I- receive only the HTTP header and ignore the entire page content;
• -j- read and send cookies from a file;
• -J- remove header from request;
• -L- accept and process redirects;
• -s- maximum number of redirections using Location;
• -o- output page content to a file;
• -O- save content to a file with the name of the page or file on the server;
• -p- use a proxy;
• --proto- indicate the protocol to be used;
• -R- save the last modification time of a remote file;
• -s- display a minimum of information about errors;
• -S- display error messages;
• -T- upload the file to the server;
• -v- the most detailed output;
• -y- minimum download speed;
• -Y- maximum download speed;
• -z- download the file only if it was modified later than the specified time;
• -V- display the version.

This is by no means all of the options for curl linux, but it lists the basics that you will need to use.

How to use curl?

We've covered everything related to the theory of working with the curl utility, now it's time to move on to practice and look at examples of the curl command.

The most common task is this. Downloading the file is very simple. To do this, just pass the file name or html page to the utility in the parameters:

curl https://raw.githubusercontent.com/curl/curl/master/README.md

But here one surprise awaits you: the entire contents of the file will be sent to standard output. To write it to any file use:

curl -o readme.txt https://raw.githubusercontent.com/curl/curl/master/README.md

And if you want the resulting file to be named the same as the file on the server, use the -O option:

curl -O https://raw.githubusercontent.com/curl/curl/master/README.md

curl -# -C - -O https://cdn.kernel.org/pub/linux/kernel/v4.x/testing/linux-4.11-rc7.tar.xz

If necessary, you can download several files with one command:

curl -O https://raw.githubusercontent.com/curl/curl/master/README.md -O https://raw.githubusercontent.com/curl/curl/master/README

Another thing that may be useful for an administrator is to only download a file if it has been modified:

curl -z 21-Dec-17 https://raw.githubusercontent.com/curl/curl/master/README.md -O https://raw.githubusercontent.com/curl/curl/master/README

Speed ​​Limit

You can limit the download speed to the required limit so as not to overload the network using the -Y option:

curl --limit-rate 50K -O https://cdn.kernel.org/pub/linux/kernel/v4.x/testing/linux-4.11-rc7.tar.xz

Here you need to specify the number of kilobytes per second that can be downloaded. You can also terminate the connection if the speed is not enough, use the -Y option to do this:

curl -Y 100 -O https://raw.githubusercontent.com/curl/curl/master/README.md

Transferring files

curl -T login.txt ftp://speedtest.tele2.net/upload/

Or let’s check that the file is sent via HTTP; there is a special service for this:

curl -T ~/login.txt http://posttestserver.com/post.php

In the response, the utility will tell you where you can find the downloaded file.

Sending POST data

You can send not only files, but also any data using the POST method. Let me remind you that this method is used to send data of various forms. To send such a request, use the -d option. For testing we will use the same service:

curl -d "field1=val&fileld2=val1"http://posttestserver.com/post.php

If you are not happy with this submission option, you can pretend to submit the form. There is an option for this -F:

curl -F "password=@pass;type=text/plain" http://posttestserver.com/post.php

Here we pass the password field with the form as plain text, in the same way you can pass several parameters.

Sending and receiving cookies

Cookies are used by websites to store certain information on the user's side. This may be necessary, for example, for authentication. You can send and receive Cookies using curl. To save the received Cookies to a file, use the -c option:

curl -c cookie.txt http://posttestserver.com/post.php

You can then send the curl cookie back:

curl -b cookie.txt http://posttestserver.com/post.php

Header transmission and analysis

We don't always necessarily need the content of the page. Sometimes only the headlines can be interesting. To display only them there is the -I option:

curl -I https://site

And the -H option allows you to send several or more to the server, for example, you can pass the If-Modified-Since header so that the page is returned only if it has been modified:

curl authentication

If the server requires one of the common types of authentication, such as HTTP Basic or FTP, then curl can handle this task very easily. To specify authentication details, simply specify them separated by a colon in the -u option:

curl -u ftpuser:ftppass -T - ftp://ftp.testserver.com/myfile_1.txt

Authentication on HTTP servers will be performed in the same way.

Using a proxy

If you need to use a proxy server to download files, then that is also very simple. It is enough to specify the proxy server address in the -x option:

curl -x proxysever.test.com:3128 http://google.co.in

conclusions

In this article, we looked at how to use curl, why this utility is needed and its main capabilities. Despite their similarity with, they are very different. The curl linux command is designed more for analyzing and simulating various actions on the server, while wget is more suitable for downloading files and crawling sites.

This article will talk about such a powerful tool as cURL, as well as the library for PHP that provides access to this tool - libcurl. What is all this for? To communicate with the server using data transfer protocols, for example, http or ftp. The rest of the protocols are not particularly interesting to us; if someone wants to delve deeper into this topic, they will have to dig up English-language resources, and this article will contain the basics and examples of use.

What exactly are cURL and libcurl? General points

So, the libcurl library provides us with the ability to transmit data to the server and receive responses from it. What does this give us? The ability to emulate user behavior or ! You can receive the contents of pages for subsequent parsing, you can receive service response headers and programmatically log in to sites, create scripts for posting messages (for example, on Twitter or on forums) or information. Everything is limited only by your imagination!

Installing cURL on Denwer (Denver). How to start using libcurl?

The first thing we have to do is install the library. On my local computer I use the Denwer build, like the vast majority of novice webmasters, for whom the article is intended. Experienced users who independently install the php+apache+mysql combination will be able to install cURL, it’s not for me to explain to them how this is done;) And we, beginners, use ready-made solutions to make it easier. Therefore, install libcurl as follows:

• Download the ready-made extension package “PHP5: additional modules”.
• Accordingly, we install it. Nothing complicated, agree :)
• Open the file in Notepad (I always recommend Notepad++): X:/webservers/usr/local/php5/php.ini //where X is your drive where the webserver is installed

  and remove the semicolon at the beginning of the terms:

  ;extension=php_curl.dll

• We are restarting the Denver server.

Ready. To check the functionality of the library, you can call the phpinfo() function and find the line there: cURL support enabled. Congratulations on your first victory.

Description of cURL and first steps

To start working with the tool, it needs to be initialized. This is done as follows:

$ch = curl_init();

We used the cURL session initialization function. In this case, you can set the URL right away, like this:

$ch = curl_init("https://site");

And you can do this later, in the options. The order in which the options are installed does not matter. This is done by another function:

Curl_setopt (resource ch, string option, mixed value)

We have already created the first parameter of this function, that is, resource ch, just above, but there are a lot of option and value parameters. I think that you shouldn’t copy-paste them all here, but just give a link to a detailed description of the function, I hope no one will be offended: curl_setopt.

I’ll give an example of setting options using a URL as an example:

$url = "https://site"; curl_setopt($ch, CURLOPT_URL,$url);

A couple more examples of setting options: let's get the server response header, without getting the page itself:

Curl_setopt($ch, CURLOPT_HEADER, 1); // read the header curl_setopt($ch, CURLOPT_NOBODY, 1); // read ONLY the header without the body

So, we have initialized the session, set the parameters we need, now we execute the resulting request, close the session and display the result:

$result = curl_exec($ch); curl_close($ch); echo $result;

As a result, we get our first fully working example of using the libcurl library:

$ch = curl_init(); $url = "https://site"; curl_setopt($ch, CURLOPT_URL,$url); curl_setopt($ch, CURLOPT_HEADER, 1); // read the header curl_setopt($ch, CURLOPT_NOBODY, 1); // read ONLY the header without the body $result = curl_exec($ch); curl_close($ch); echo $result;

How it works, I hope, is clear, because we looked at each step separately :) As a result, we receive an HTTP response header from the server, which we will definitely analyze below in order to better understand all the stages of interaction between the browser and the server:

HTTP/1.1 200 OK Server: nginx/1.2..php 1

Fabulous! We received the response header from the server and tested the library in action. How is this useful to us? Because now you can roughly imagine the sequence of actions when working with cURL:

• Initialize session (curl_init)
• Set the options we need (curl_setopt)
• Execute the received request (curl_exec)
• End session (curl_close)

HTTP request header structure

For example, I turned to the ya.ru page and looked at the generated browser request and the response received from the server. Here they are:
Request
GET / HTTP/1.1 - We are trying to get the page at /, that is, the main page located in the root of the folder. We use protocol version 1.1.
User-Agent: Opera/9.80 (Windows NT 6.1; WOW64) Presto/2.12.388 Version/12.14— We introduce ourselves to the server, we are the Opera browser.
Host: ya.ru — Domain name of the requested resource.
Accept: text/html, application/xml;q=0.9, application/xhtml+xml, image/png, image/webp, image/jpeg, image/gif, image/x-xbitmap, */*;q=0.1— List of acceptable resource formats.
Accept-Language: ru-RU,ru;q=0.9,en;q=0.8— List of supported languages.
Accept-Encoding: gzip, deflate— Supported encoding methods.
Cookie: yandexuid=ХХХХХ - Cookies, if necessary.
Connection: Keep-Alive - Please do not break the connection and stay in touch.
Answer
HTTP/1.1 200 Ok - We receive a response with code 200, which means everything is OK.
Server: nginx - The server introduced itself - this is nginx.
Date: Sun, 10 Mar 2013 14:10:50 GMT— Current date and time on the server.
Content-Type: text/html; charset=UTF-8— Content type and encoding.
Connection: close - The server does not want to maintain a permanent connection with us, so it immediately closes it. A new connection will be established for the next request.
Cache-Control: no-cache,no-store,max-age=0,must-revalidate— Caching management. In this case it is disabled.
Expires: Sun, 10 Mar 2013 14:10:50 GMT— Date of expected expiration of the session. In our case, it coincides with the opening time, since the server immediately closed it, immediately after processing.
Last-Modified: Sun, 10 Mar 2013 14:10:50 GMT— Time of last modification.
Content-Encoding: gzip — Method of encoding information.
A complete list of all parameters that can be found in the HTTP request header can be found on Wikipedia.
Now you have a rough idea of ​​how your browser and web server communicate with each other. This is very useful to know and understand, because we will try to emulate browser actions using the libcurl library. Go ahead.

Example of working with the library

I believe that after some general points are already clear and everything seems to be clear, then it’s time to move on to practice and hone your skills using example. Personally, my hands are always itching to try everything in practice :)

Since cURL is so good for parsers, let's consider the function of getting the page code by its address. In this case, the output will be an array with the title, page content, and even error codes if something goes wrong.

Function get_web_page($url) ( $uagent = "Opera/9.80 (Windows NT 6.1; WOW64) Presto/2.12.388 Version/12.14"; $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // returns the web page curl_setopt($ch, CURLOPT_HEADER, 0); // does not return headers curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1); // follows redirects curl_setopt($ch, CURLOPT_ENCODING, ""); // processes all encodings curl_setopt($ch, CURLOPT_USERAGENT, $uagent); // useragent curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 120); // connection timeout curl_setopt($ch, CURLOPT_TIMEOUT, 120); // response timeout curl_setopt($ch, CURLOPT_MAXREDIRS , 10); // stop after the 10th redirect $content = curl_exec($ch); $err = curl_errno($ch); $errmsg = curl_error($ch); $header = curl_getinfo($ch); curl_close( $ch); $header["errno"] = $err; $header["errmsg"] = $errmsg; $header["content"] = $content; return $header; )

Input parameters:
url — page or site address.
Output parameter values ​​(array with three elements):
header['errno'] - if something went wrong, there will be an error code here.
header[‘errmsg’] – the error text will appear here.
header['content'] - the actual page\file\image, etc.

We use the function, for example, like this:

$result = get_web_page("https://ya.ru"); if (($result["errno"] != 0)||($result["http_code"] != 200)) ( echo $result["errmsg"]; ) else ( $page = $result["content "]; echo $page; )

Everything should go without errors and you will receive the page code in the $page variable. If we try to get the non-existent page yaaaaaaaaaaaa.ru, we will get the error:

Could not resolve host: yaaaaaaaaaaaa.ru; Host not found

Everything is processed correctly and beautifully :)
Then you can do whatever you want with the page code, for example, parse it with regular expressions. But that's all in the next lessons, but for now let's stop at this.

JavaScript is blocked in your browser. Please enable JavaScript for the site to function!

Curl

PHP supports libcurl, a library created by Daniel Stenberg that makes it possible to connect to different types of servers and using different protocols.
libcurl currently supports http, https, ftp, gopher, telnet, dict, file and ldap protocols.
libcurl also supports HTTPS certificates, HTTP POST, HTTP PUT, FTP upload (this can also be done with the ftp PHP extension), HTTP form-based upload, proxies, cookies, and user+password authentication.

These functions were introduced in PHP 4.0.2.

curl_init

curl_init - initializes a CURL session.

Description

resource curl_init()

Function curl_init() initializes a new session and returns a CURL handle for use in the , and functions. If the optional parameter url is provided, then the CURLOPT_URL option will receive the value of this parameter. You can manually install it using the .

curl_setopt

curl_setopt - sets options for CURL transfer/transfer.

Description

bool curl_setopt(resource ch, string option, mixed value)

Function curl_setopt() sets options for the CURL session identified by the parameter ch. Parameter option is the option you want to set, and value this is the option value option .

Parameter value must be long for the following options (specified by parameter option):

• CURLOPT_INFILESIZE: If you are uploading a file to a remote site, this option should be used to tell PHP what the expected infile size will be.
• CURLOPT_VERBOSE: Set this option to a non-zero value if you want CURL to report all actions.
• CURLOPT_HEADER: Set this option to a non-zero value if you want the header to be included in the output.
• CURLOPT_NOPROGRESS: Set this option to a non-zero value if you do not want PHP to display a CURL transfer progress indicator. (PHP automatically sets this option to a non-zero value; you only need to change it when debugging.)
• CURLOPT_NOBODY: Set this option to a non-zero value if you do not want the body to be included in the output.
• CURLOPT_FAILONERROR: Set this option to a non-zero value if you want PHP to silently exit if the returned HTTP code is greater than 300. By default, the page is returned normally with the code ignored.
• CURLOPT_UPLOAD: Set this option to a non-zero value if you want PHP to prepare the file for upload.
• CURLOPT_POST: Set this option to a non-zero value if you want PHP to perform regular HTTP POST. This POST is in the normal form application/x-www-form-urlencoded, most commonly used by HTML forms.
• CURLOPT_FTPLISTONLY: Set this option to a non-zero value and PHP will list FTP directory names.
• CURLOPT_FTPAPPEND: Set this option to a non-zero value and PHP will append to the remote file instead of overwriting it.
• CURLOPT_NETRC: Set this option to a non-zero value and PHP will scan your ~./netrc file to find your username and password for the remote site you are connecting to.
• CURLOPT_FOLLOWLOCATION: Set this option to a non-zero value to follow any "Location: " header that the server sends as part of an HTTP header (note that this is recursion, PHP will follow all "Location: " -headers" that are sent. )
• CURLOPT_PUT: Set this option to a non-zero value to HTTP PUT the file. The file for PUT must be set using CURLOPT_INFILE and CURLOPT_INFILESIZE.
• CURLOPT_MUTE: Set this option to a non-zero value and PHP will operate hidden with respect to CURL functions.
• CURLOPT_TIMEOUT: Pass a long as a parameter that contains the maximum time in seconds that you allow CURL functions to run.
• CURLOPT_CONNECTTIMEOUT: Pass a long as a parameter that contains the maximum time, in seconds, that you allow to wait when attempting to connect. Use 0 to wait forever.
• CURLOPT_LOW_SPEED_LIMIT: Pass a long as a parameter that contains the transfer speed, in bytes per second, below which the transfer must run during execution CURLOPT_LOW_SPEED_TIME, in seconds, for PHP to consider it too slow and abort it.
• CURLOPT_LOW_SPEED_TIME: Pass a long as a parameter that contains the time in seconds below which the transfer must run while running CURLOPT_LOW_SPEED_LIMIT for PHP to consider it too slow and abort it.
• CURLOPT_RESUME_FROM: Pass long as a parameter that contains the byte offset at which the transfer should start.
• CURLOPT_SSLVERSION: Pass a long as a parameter that contains the SSL version to use (2 or 3). By default, PHP tries to determine this itself, although in some cases you are required to set this manually.
• CURLOPT_SSL_VERIFYHOST: Pass long if CURL should check the common name of the peer certificate in an SSL handshake. A value of 1 indicates that we should check for the existence of a common /common name, a value of 2 indicates that we should ensure that it matches the provided hostname.
• CURLOPT_TIMECONDITION: Pass a long as a parameter that determines how CURLOPT_TIMEVALUE is treated. You can set this parameter to TIMECOND_IFMODSINCE or TIMECOND_ISUNMODSINCE. This only works for HTTP.
• CURLOPT_TIMEVALUE: Pass a long as a parameter, which is the time in seconds since January 1, 1970. This time is used as specified by the CURLOPT_TIMEVALUE option, or the default TIMECOND_IFMODSINCE will be used.
• CURLOPT_RETURNTRANSFER: Pass a non-zero value if you want CURL to directly return the received information instead of printing it directly.

Parameter value must be a string for the following parameter values option :

The following options expect a file descriptor, which is obtained using the function fopen() :

• CURLOPT_FILE: The file where the output of your transfer should be placed, by default it is STDOUT.
• CURLOPT_INFILE: The file from which your transfer input comes.
• CURLOPT_WRITEHEADER: File for recording the header part of the output.
• CURLOPT_STDERR: File to record errors, instead of stderr.

Parameter value long write_callback (resource ch, string data)( ... return strlen($data);) option :

• CURLOPT_WRITEFUNCTION: .
• CURLOPT_HEADERFUNCTION: .

Parameter value should be a function of the following form string read_callback (resource ch, resource fd, long length)() for the following parameter values option :

• CURLOPT_READFUNCTION: .

curl_exec

curl_exec - executes a CURL session.

Description

bool curl_exec(resource ch)

This function should be called after you have initialized a CURL session and all options for that session have already been set. Its purpose is simply to execute a predefined CURL session (specified in the parameter ch).

curl_close

curl_close - closes the CURL session.

Description

void curl_close(resource ch)

This function closes the CURL session and releases all resources. CURL handle ch is also deleted.

curl_errno

curl_errno - returns an integer containing the last error number.

Description

Example 1: Initializing a new CURL session and retrieving a web page.

Example 2: Using PHP's CURL module to get example.com

Example 3: Checking URL Accessibility Using PHP's CURL

Example 4: Separating the header from the body obtained using PHP's CURL

Example 5: Determining a Referral URL Using PHP's CURL

the problem: curl_setopt($ch,FOLLOW_LOCATION,1); the error: trouble with open_basedir and safe_mode the solution: a function already developed by someone the solution n 2: the same function, modifed, works great for me..= $curl_max_loops) ( $curl_loops = 0; return FALSE; ) curl_setopt($ch, CURLOPT_HEADER, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $data = curl_exec($ch); list($header, $data) = explode("\n\n", $data, 2); $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($http_code == 301 || $http_code == 302) ( $matches = ; preg_match("/Location:(.*?)\n/", $header, $matches); $url = @parse_url(trim (array_pop($matches))); if (!$url) ( //couldn"t process the url to redirect to $curl_loops = 0; return $data; ) $last_url = parse_url(curl_getinfo($ch, CURLINFO_EFFECTIVE_URL)) ; if (!$url["scheme"]) $url["scheme"] = $last_url["scheme"]; if (!$url["host"]) $url["host"] = $last_url[ "host"]; if (!$url["path"]) $url["path"] = $last_url["path"]; $new_url = $url["scheme"] . "://" . $ url["host"] . $url["path"] . ($url["query"]?"?".$url["query"]:""); curl_setopt($ch, CURLOPT_URL, $new_url) ; debug("Redirecting to", $new_url); return curl_redir_exec($ch); ) else ( $curl_loops=0; return $data; ) ) ?>
just use this function without de FOLLOW_LOCATION and should work. the problem was that when you get to the line where you return the data if http_code was different than 301 oe 302, $data has obsolete information or none. so $debbbb does the job.

Example 6: Parsing a cookie from the header using CURL PHP

Sometimes you can"t use CURLOPT_COOKIEJAR and CURLOPT_COOKIEFILE becoz of the server php-settings(They say u may grab any files from server using these options). Here is the solution 1)Don"t use CURLOPT_FOLLOWLOCATION 2)Use curl_setopt($ch, CURLOPT_HEADER, 1) 3)Grab from the header cookies like this: preg_match_all("|Set-Cookie: (.*);|U", $content, $results); $cookies = implode(";", $results); 4)Set them using curl_setopt($ch, CURLOPT_COOKIE, $cookies);

Example 7: Parsing a cookie from the header using CURL PHP

As Yevgen mentioned earlier sometimes we can"t use CURLOPT_COOKIEJAR and CURLOPT_COOKIEFILE. Below is a header callback function I wrote back in January that lets you maintain cookies between cURL requests. Cookies are added to $ch during all requests even during redirection, so you can use it together with CURLOPT_FOLLOWLOCATION. Here is the code: function read_header($ch, $string) ( global $location; #keep track of location/redirects global $cookiearr; #store cookies here global $ch; # ^overrides the function param $ch # this is okay because we need to # update the global $ch with # new cookies $length = strlen($string); if(!strncmp($string, "Location:", 9)) ( #keep track of last redirect $location = trim(substr($string, 9, -1)); ) if(!strncmp($string, "Set-Cookie:", 11)) ( #get the cookie $cookiestr = trim(substr( $string, 11, -1)); $cookie = explode(";", $cookiestr); $cookie = explode("=", $cookie); $cookiename = trim(array_shift($cookie)); $cookiearr [$cookiename] = trim(implode("=", $cookie)); ) $cookie = ""; if(trim($string) == "") ( #execute only at end of header foreach ($cookiearr as $key=>$value) ( ​​$cookie .= "$key=$value; "; ) curl_setopt($ ch, CURLOPT_COOKIE, $cookie); ) return $length; ) curl_setopt($ch, CURLOPT_HEADERFUNCTION, "read_header"); This code assumes that you will reuse $ch without initializing it every time (call curl_init only once, in the beginning). If you need to initialize $ch again at any point in your code you can access the currently stored cookies in $cookiearr and include them in the new $ch. I wrote this function before I had enough experience with regular expressions so you won"t find any preg_match calls here. I have used this code for quite a while and without any problems accessing gmail, yahoo, hotmail, aol etc. where I had to go through login and a few pages before getting to what I was looking for.

Example 8: Setting up a header load handler using CURL PHP

Using cURL, I needed to call a third-party script which was returning binary data as attachment to pass on retrieved data again as attachment. Problem was that the third-party script occassionally returned HTTP errors and I wanted to avoid passing on zero-length attachment in such cases. Combination of using CURLOPT_FAILONERROR and CURLOPT_HEADERFUNCTION callback helped to process the third-party script HTTP errors neatly: function curlHeaderCallback($resURL, $strHeader) ( if (preg_match("/^HTTP/i", $strHeader)) ( header($strHeader ); header("Content-Disposition: attachment; filename="file-name.zip""); ) return strlen($strHeader); ) $resURL = curl_init("http://site/"); curl_setopt($resURL, CURLOPT_BINARYTRANSFER, 1); curl_setopt($resURL, CURLOPT_HEADERFUNCTION, "curlHeaderCallback"); curl_setopt($resURL, CURLOPT_FAILONERROR, 1); curl_exec($resURL); $intReturnCode = curl_getinfo($resURL, CURLINFO_HTTP_CODE); curl_close($resURL); if ($intReturnCode != 200) ( print "Error with code: " . $intReturnCode; )

Example 9. Saving a page to a file and calculating the transfer rate using CURL PHP

WritePageToFile("http://es.php.net", "es.php.net.txt"); function WritePageToFile($sHTMLpage, $sTxtfile) ( $sh = curl_init($sHTMLpage); $hFile = FOpen($sTxtfile, "w"); curl_setopt($sh, CURLOPT_FILE, $hFile); curl_setopt($sh, CURLOPT_HEADER, 0); curl_exec ($sh); $sAverageSpeedDownload = curl_getInfo($sh, CURLINFO_SPEED_DOWNLOAD); $sAverageSpeedUpload = curl_getInfo($sh, CURLINFO_SPEED_UPLOAD); echo "

"; echo "Average speed download == " . $sAverageSpeedDownload . " 
"; echo "Average Speed ​​upload == " . $sAverageSpeedUpload ." 
"; echo " 
"; $aCURLinfo = curl_getInfo($sh); print_r($aCURLinfo); echo "

"; curl_close($sh); FClose ($hFile); echo "( See the file "".$sTxtfile."" in the same path of the hosting." " to where this script PHP).
"; }

Example 9. Receiving a page via an SSL connection (https)

$ch=curl_init("https://site"); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // Disable the error "SSL certificate problem, verify that the CA cert is OK" curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); // Disable the error "SSL: certificate subject name "hostname.ru" does not match target host name "123.123"" curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); $out=curl_exec($ch); //$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); //echo "http_code=".$http_code,", err=".curl_error($ch); curl_close($ch);

Example 10: Using sessions and cookies in curl

$cookie_filename=sys_get_temp_dir()+"/cookie.tmp"; $curl=curl_init("http://site"); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl, CURLOPT_COOKIEJAR, $cookie_filename);//save received COOKIEs to a file curl_setopt($curl, CURLOPT_COOKIEFILE, $cookie_filename); //send to the server the COOKIEs received from it during authorization $out=curl_exec($curl);

Example 11: File upload and multidimensional array in Curl. CURLOPT_POSTFIELDS + CurlFile

If you need to send a multidimensional array and a file in a POST request, you will encounter an insoluble problem. If you pass a multidimensional array to CURLOPT_POSTFIELDS, the second level will be passed as the string "Array". If you convert using http_build_query, you will not be able to transfer the file.

Below is a function for encoding a two-dimensional array with file loading for Curl, which will work in both older versions of PHP 5.3, PHP 5.4, and PHP 5.6

/** converts a multi-dimensional array to a one-dimensional array using complex indexes and replaces the @ in the prefix with CurlFile for use in Curl * @param $inputArray * @param string $inputKey * @return array $requestVars = array("id" => array( 1, 2,"id"=>1234), "name" => "log", "logfile" => "@/tmp/test.log"); we get: ["id"]=> int(1) ["id"]=> int(2) ["id"]=> int(1234) ["name"]=> string(3) "log" [ "logfile"]=> string(13) "/tmp/test.log" ) */ function convertToStringArray($inputArray, $inputKey="") ( $resultArray=; foreach ($inputArray as $key => $value) ( $tmpKey = (bool)$inputKey ? $inputKey."[$key]" : $key; if (is_array($value)) ( $resultArray+=convertToStringArray($value, $tmpKey); ) elseif ($value = = "@")( $resultArray[$tmpKey] = (class_exists(" CURLFile ", false)) ? new CurlFile(ltrim($value, "@")) : $value; ) else ( $resultArray[$tmpKey] = $value; ) ) return $resultArray; ) // check $requestVars = array("id" => array(1, 2,"id"=>1234), "name" => "log", "logfile" => "@/tmp/test.log"); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "site"); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, convertToStringArray($requestVars)); $res = curl_exec($ch); curl_close($ch); Application examples of using Curl