CURL Basics with Example

In the PHP installation libcurl provides the CURL functionality which enables the user to communicate with different types of servers with different types of protocols like : http, ftp, https, file in which http is widely used.

It supports different http methods(GET,POST,PUT) while communicating or submitting information to the server.

Abbreviation:Called as cURL ( Client URL or Client URL library)

Enabling curl: There is a PHP curl dll extension defined in the php.ini configuration file
;extension=php_curl.dll
Remove semi-colon before this and save-restart the server.

Basics:
curl_init - initializes the curl session
eg: $request = curl_init();  // initiate curl object

curl_setopt - sets the curl transfer options like http methods and values, header, ssl, encoding etc. Some options(OPT) are as follows:-

curl_setopt($request, CURLOPT_URL, $requestUrl);  // sets the url to which curl has to communicate like : https://example.com/Portal/downloadfile.do  , http://example.com/action

curl_setopt($request, CURLOPT_SSL_VERIFYPEER, false);  // true or false to set whether to verify certificate or not

curl_setopt($request, CURLOPT_SSL_VERIFYHOST, false);  // 1 or 2 to set whether to check for the common name with the ssl peer or  to check for common name and hostname both with ssl peer

curl_setopt($request, CURLOPT_FORBID_REUSE, true);   // true to close session explicitly when process ends

curl_setopt($request, CURLOPT_FRESH_CONNECT, true);  // true to avoid cached connection

curl_setopt($request, CURLOPT_TIMEOUT, 300);  //set timeout to 5 mins

curl_setopt($request,CURLOPT_ENCODING, 1);  // 1 to enable decoding of the response in case response is decoded like : gzip or deflate

curl_setopt($request, CURLOPT_HEADER, false);   // true or false for getting the header in the output

curl_setopt($request, CURLOPT_POST, true);  // true for a HTTP POST

curl_setopt($request, CURLOPT_POSTFIELDS, $postString);  // contains the posting parameters like: height=100&weight=50&depth=10

curl_setopt($request, CURLOPT_RETURNTRANSFER, true);  // true to get the output as string otherwise false

curl_setopt($request, CURLOPT_FILE, $fp); // $fp is the file pointer to which the output will be written ( use it when dealing with the file download or response as a file like: pdf, images or xml )

curl_exec - execute the cURL session
eg: $response = curl_exec($request);  // execute curl request and get the response

curl_close - ends the close session
eg: curl_close ($request);  // ends curl object or session

Getting the return info:
$returnInfo = curl_getinfo($request);  // get the info of response like content_type, http_code, filetime, total_time and $request is the CURL object


Some basic CURL problems and solutions:
1- CURL is not enabled on server then enable it as described above with php.ini configuration file.

2- sometimes we get rough valued response( curl decoding error in response ) with special character like:
^ghfdtbf8340*9)GkjBKJTg&^)(_mm..;j>”GhY^%hG&j$%
then check for encoding type for the response string and set encoding option as given above

3- If getting problem with downloading file in response( pdf/images ) then look for file option in curl and also check for the content_type in curl info whether you are getting the desired file type or not


Notes/attention:
1- Be particular while setting the CURL option as this makes the request heavy and complex.

2- Always use curl_close to close the session and don’t rely on explicit session ending.





Example:
Here i am giving a simple example in which i am trying to get a pdf file as a response and i am writing the pdf response to my local pdf file. Here is the code:-

$feed_url="https://<hostURL>/Portal/downloadfile.do";
$path = "./upload/tmp_".$_SESSION['userId'].".pdf"; // temporary file to write

     
$fp = fopen($path, 'w');

// ***** download the pdf
$request = curl_init(); // initiate curl object
curl_setopt($request, CURLOPT_SSLVERSION,3);
curl_setopt($request, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($request, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($request, CURLOPT_HEADER, true);

// SET URL FOR THE POST FORM
curl_setopt($request, CURLOPT_URL, $feed_url);

// ENABLE HTTP POST
curl_setopt ($request, CURLOPT_POST, 1);

// SET POST PARAMETERS : FORM VALUES FOR EACH FIELD
curl_setopt ($request, CURLOPT_POSTFIELDS, "fileNo=".$_REQUEST['fileNo']);

curl_setopt($request, CURLOPT_BINARYTRANSFER, 1);
curl_setopt($request, CURLOPT_FILE, $fp);
curl_setopt($request, CURLOPT_TIMEOUT, 300); //set timeout to 5 mins

$fileopt = curl_exec($request); // execute curl post

$http_status = curl_getinfo($request);

curl_close ($request); // close curl object
fclose($fp); //close file


References: 

http://php.net/manual/en/book.curl.php
http://php.net/manual/en/ref.curl.php
http://en.wikipedia.org/wiki/CURL


Thanks for your valuable comments