The PHP cURL library adds support for requesting and submitting data over HTTP connections. This article will show you how to use it.
There are a plethora of useful online services you can pull data from. From mapping to currency conversion, weather, flight schedules, language translations (in fact, just look at a big list of them here), these services, called APIs (Application Programming Interface), allow you to interact with massive databases of information over the HTTP protocol.
PHP includes the tools to do this in its cURL library – an implementation of the cURL command-line program.
Enabling cURL Support in PHP
To use the cURL library, first, you must install support for it in PHP. It may already be installed depending on how your system was initially configured – if it isn’t, here’s how:
Installing on Ubuntu/Debian
If you’re on an Ubuntu or Debian system and using the default PHP version for your distribution, simply run the following commands:
sudo apt update sudo apt install curl sudo apt install php-curl
If you are running a specific version of PHP, you will need to install cURL for that version.
To find out which version of PHP you are running:
php -v
The version of PHP you are running will be displayed. You can then install the version of PHP cURL you require:
sudo apt update sudo apt install curl sudo apt install php5.6-curl
Above, cURL for PHP version 5.6 is installed.
Installing on Fedora/RedHat Distributions
Install cURL and the cURL PHP library on Fedora/RedHat based distribution with the following commands:
sudo yum install curl sudo yum install php-curl
Retrieving and Saving Data
The simplest way to use cURL is to simply grab the contents of a web page.
This example will grab the contents of https://linuxscrew.com and save it to a file.
// Create a cURL object, initialised to read from a given web page
$curl = curl_init("https://www.linuxscrew.com/");
// Create a file handler which will be used to write to a file on your filesystem
$file = fopen("curl_demo.html", "w");
// Set cURL options - this is how cURL behaviour is defined
// Tell cURL to output data received to the given file
curl_setopt($curl, CURLOPT_FILE, $file);
// Tell cURL to not retrieve headers and include them in the output
curl_setopt($curl, CURLOPT_HEADER, false);
// Execute the cURL command with the information and options provided above
curl_exec($curl);
// If there is an error, write the error to the file
// cURL errors are detected by checking the cURL object with the curl_error() function
if(curl_error($curl)) {
fwrite($file, curl_error($curl));
}
// Close the connection created by cURL
curl_close($curl);
// Release the file so that it can be used by other processes
fclose($file);
The comments in the above example will explain what each step is doing.
Of course, as cURL is only grabbing the HTML and not the images, stylesheets, and other assets used by the webpage, the output is pretty ugly – but it’s a simple demonstration of how the library can be used.
Sending/Receiving Data To/From an API
This example sends a GET request using PHP cURL. Note that the $url and query defined are just examples – you’ll need to insert the URL and a compatible query to the API you wish to use.
// Define the URL of the API endpoint you wish to communicate with
$url = 'https://example.com';
// Define the query string parameters that will be sent with the request
// The query string is data appended to the URL in a GET request which is often used for supplying more information about what data is requested - in this case we want to search for records with a matching country, and to limit the maximum number of results
$query = [
'country' => 'Australia',
'maxResults' => 5
];
// Initialise cURL with the URL and query parameters
// This is done by converting the $query array to a HTTP query string using http_build_query() and then appending it to the $url
$curl = curl_init($url . '?' . http_build_query($query));
// Set cURL options
// Tell curl to return the data transferred as a string from curl_exec() when it is called instead of outputting the data directly
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// Set the headers for the request - this is usually where things like the API key or username/password are defined for accessing private APIs
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'X-API_KEY: supersecretapikey'
]);
// REST APIs return their data in the JSON format
// As CURLOPT_RETURNTRANSFER is set above, curl_exec will return the text of the response it receives directly. This JSON formatted text can then be passed straight to json_decode() to convert from text to an object which can be processed
$response = json_decode(curl_exec($curl), true);
// Close the connection
curl_close($curl);
//Print the formatted data retrieved from the API
print_r($response);
The specifics in the above example will change depending on what the API you want to communicate with is and does, but the broad strokes will be the same – define the query you wish to submit (if any), set the cURL options, and then execute cURL to retrieve the data.
Making POST Requests with cURL
// Define the URL of the API endpoint you wish to communicate with
$url = 'https://example.com';
// The data to be POSTed to the API - in this example it's sending the details of a person to be stored
$postData = [
'name' => 'Fred',
'Age' => 51
];
// Initialise cURL
$curl = curl_init($url);
// Set cURL options
// Tell cURL that this will be a POST request
curl_setopt($curl, CURLOPT_POST, true);
//Construct and include the POST data for the request
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($postData));
// Tell curl to return the data transferred as a string from curl_exec() when it is called instead of outputting the data directly
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// REST APIs return their data in the JSON format
// As CURLOPT_RETURNTRANSFER is set above, curl_exec will return the text of the response it receives directly. This JSON formatted text can then be passed straight to json_decode() to convert from text to an object which can be processed
$response = json_decode(curl_exec($curl), true);
// Close the connection
curl_close($curl);
//Print the formatted data retrieved from the API
print_r($response);
cURL Does Other Stuff, Too
cURL doesn’t just talk HTTP – you can interact with other kinds of servers/protocols, like mail servers and file servers.
To find out more about what can be done with PHP cURL, check out the official documentation.
