cURL Requests in PHP

Introduction

cURL allows transfer of data across a wide variety of protocols, and is a very powerful system. It's widely used as a way to send data across websites, including things like API interaction and OAuth. cURL is unrestricted in what it can do, from the basic HTTP request, to the more complex FTP upload or interaction with an authentication enclosed HTTPS site. I have had to use it in many implementations so I decided to do write about it.

Basics

We need to first instantiate an instance of cURL - we can do this by calling the function curl_init();, which returns a cURL resource. This function takes one parameter which is the URL that you want to send the request to.

Settings

Once you've got a cURL resource, we can begin to assign some settings, below is a list of some of the core ones:

CURLOPT_RETURNTRANSFER - Return the response as a string instead of outputting it to the screen.

CURLOPT_CONNECTTIMEOUT - Number of seconds to spend attempting to connect

CURLOPT_TIMEOUT - Number of seconds to allow cURL to execute

CURLOPT_USERAGENT - Useragent string to use for request

CURLOPT_URL - URL to send request to

CURLOPT_POST - Send request as POST

CURLOPT_POSTFIELDS - Array of data to POST in request

You can set a setting by using the curl_setopt() method, which takes three parameters, the cURL resource, the setting and the value. So, to set the URL that we're sending the request to as http://testweb.com:

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'http://testweb.com');  

You can set the URL by sending a parameter through when getting the cURL resource:

$curl = curl_init('http://testweb.com');

It is possible to set multiple settings at one time by passing through an array of settings and values to the function ```

curl_setopt_array()  
$curl = curl_init();
curl_setopt_array($curl, array(  
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'http://testweb.com'
));

Sending request

When all of the options are sent, and the request is ready to send, we can call the curl_exec() method which will execute the cURL request. This function can return three different things:

false - if there is an error executing the request

true - if the request executed without error and CURLOPT_RETURNTRANSFER is set to false

The result - if the request executed without error and CURLOPT_RETURNTRANSFER is set to true

Using the previous example, if you are wanting to get the result back, you would use the following:

$result = curl_exec($curl);

With $result now containing the response from the page - which might be JSON, a string or a full site's HTML.

Close Request

When you've sent a request and got the result back, you should look to close the cURL request so that you can free up some system resources, this is as simple as calling the curl_close() method which as with all other functions takes the resource as its parameter.

GET Request

A GET request is the default request method that is used, and is very straight forward to use, infact all of the examples so far have been GET requests. If you want to send parameters along in the request you simply append them to the URL as a query string such as http://testweb.com/?item1=value&item2=value2.

So for example to send a GET request to the above URL and return the result we would use:

Get cURL resource

$curl = curl_init();

Set some options - we are passing in a useragent too here

curl_setopt_array($curl, array(  
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'http://testweb.com/?item1=value&item2=value2',
    CURLOPT_USERAGENT => 'Sample cURL Request'
));

Send the request & save response to $resp

$resp = curl_exec($curl);

Close request to clear up some resources

curl_close($curl);  

POST Request

The sole difference between the POST and GET request syntax is the addition of one setting, two if you want to send some data. Set CURLOPT_POST to true and send an array of data through with the setting CURLOPT_POSTFIELDS

So for example switching the above GET request to be a POST request:

Get cURL resource

$curl = curl_init();

Set some options

curl_setopt_array($curl, array(  
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'http://testcURL.com',
    CURLOPT_USERAGENT => 'Sample cURL Request',
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => array(
        item1 => 'value',
        item2 => 'value2'
    )
));

Send the request & save response to $resp

$resp = curl_exec($curl);

Close request to clear up some resources

curl_close($curl);  

Errors

There are a few functions that you can use to handle errors:

curl_error() - returns a string error message, will be blank '' if the request doesn't fail. curl_errno() - which will return the cURL error number. An example usage would be:

if(!curl_exec($curl)){  
    die('Error: "' . curl_error($curl) . '" - Code: ' . curl_errno($curl));
}

You can use the setting CURLOPT_FAILONERROR as true if you want any HTTP response code greater than 400 to cause an error, instead of returning the page HTML.