The open source libcurl
is client-side URL
transfer library which supports a lot of protocols like FTP
, HTTP
, HTTPS
and works on a multitude of platforms. The PHP cURL
module let us access the functionalities provided by the library from the PHP programming language. In this tutorial we will see how to install the module and how to use it to perform simple requests.
In this tutorial you will learn:
- How to install the cURL module
- The basic steps to follow to initialiaze a cURL session and perform a request
- How to perform a GET request with PHP cURL
- How to perform a POST request with PHP cURL
Software Requirements and Conventions Used
Category | Requirements, Conventions or Software Version Used |
---|---|
System | Os-independent |
Software | The php-curl package |
Other | Basic knowdlege of PHP and HTTP |
Conventions | # – requires given linux commands to be executed with root privileges either directly as a root user or by use of sudo command$ – requires given linux commands to be executed as a regular non-privileged user |
Before we begin
Before we proceed further in this tutorial we must check that the cURL extension is installed in our system. It is almost certainty the case, however the command to install it on Fedora is:
$ sudo dnf install php-curl
To install the extension on Debian and derivatives we can instead run:
$ sudo apt-get install php-curl
On Archlinux the extension is merged into the main PHP package, so to install it we can run:
$ sudo pacman -S php
Once we are sure cURL support is enabled, we can proceed and see how to create and customize a session and perform a request.
Main steps
The steps we need to perform an HTTP request when working with cURL
are basically 4:
- Create a session;
- Customize the session by using available constants;
- Execute the session;
- Close the session;
To each one of the steps mentioned above corresponds a dedicated function, respectively:
- curl_init;
- curl_setopt;
- curl_exec;
- curl_close;
Let’s proceed in order.
Initializing a new cURL session: curl_init
To initialize a new cURL
session we use the curl_init
function. This function takes an optional argument which is the URL to be used for the request we want to perform. The argument is optional because we can alternatively pass it by specifying it as the value of the CURLOPT_URL
option, using curl_setopt
. The function returns an handler
we need to pass in the other functions as the first argument. In the example below we used the NASA open API for the “astronomic picture of the day”, sending our request to its endpoint URL:
$handler = curl_init("https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY");
Setting session options: curl_setopt
As we already said, to modify the behavior of cURL we can operate on the value of some options, referencing them by the use of some constants via the curl_setopt
function. This function takes three arguments:
- The
handler
returned by thecurl_init
function; - The
cURL constant
related to the option to modify; - The
value
to set for the option;
The function returns TRUE
on success and FALSE
on failure. The list of the constants we can use with this function is too long to be exhaustively mentioned here, however, we already learned that we can use it to set the request URL
:
curl_setopt($handler, CURLOPT_URL, "https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY");
Another often used constant is CURLOPT_RETURNTRANSFER
. The value provided for the option must be a boolean
: if set to true, when using the curl_exec
function to execute a request, the response will be returned instead of displayed directly. Here is how we can set it:
curl_setopt($handler, CURLOPT_RETURNTRANSFER, true);
In case we need to set multiple options, instead of repeatedly call curl_setopt
, we can represent the options we want to change and their values as key – value pairs into an array, and use the curl_setopt_array
function to pass them at once:
$options = [
CURLOPT_URL => "https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY",
CURLOPT_RETURNTRANSFER => true
]
curl_setopt_array($handler, $options);
The curl_setopt_array
function returns TRUE
if all the settings are applied correctly, and FALSE
as soon as an option could not be set.
Executing a session: curl_exec
Once we define the parameters and the options for our request, we can execute it: to perform such operation we use the curl_exec
function. The function takes the handler returned by curl_init
as its sole argument. By default it returns TRUE
on success and FALSE
on failure, however if the CURLOPT_RETURNTRANSFER
option is set to true
, just like we saw above, it does return the actual result of the request on success, and FALSE
on failure. When executing our request without CURLOPT_RETURNTRANSFER
, we obtain the following result:
$handler = curl_init("https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY");
curl_exec($handler);
{"copyright":"Alistair Symon","date":"2019-07-25","explanation":"In brush
strokes of interstellar dust and glowing hydrogen gas, this beautiful skyscape
is painted across the plane of our Milky Way Galaxy near the northern end of the
Great Rift and the constellation Cygnus the Swan. Composed with three different
telescopes and about 90 hours of image data the widefield mosaic spans an
impressive 24 degrees across the sky. Alpha star of Cygnus, bright, hot,
supergiant Deneb lies near top center. Crowded with stars and luminous gas
clouds Cygnus is also home to the dark, obscuring Northern Coal Sack Nebula,
extending from Deneb toward the center of the view. The reddish glow of star
forming regions NGC 7000, the North America Nebula and IC 5070, the Pelican
Nebula, are just left of Deneb. The Veil Nebula is a standout below and left of
center. A supernova remnant, the Veil is some 1,400 light years away, but many
other nebulae and star clusters are identifiable throughout the cosmic scene. Of
course, Deneb itself is also known to northern hemisphere skygazers for its
place in two asterisms -- marking the top of the Northern Cross and a vertex of
the Summer
Triangle.","hdurl":"https://apod.nasa.gov/apod/image/1907/CygnusMosaic07192000Symon.jpg","media_type":"image","service_version":"v1","title":"Cygnus
Skyscape","url":"https://apod.nasa.gov/apod/image/1907/CygnusMosaic07192000Symon_1024.jpg"}
As you can see, the result of the request (information about the astronomic picture of the day) is directly printed in the terminal. If we use the aforementioned option, the result is returned by the function, and we can, for example, use it as the value of a variable:
curl_setopt($handler, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($handler);
An important thing to notice is that responses with an HTTP status code
denoting an error, like for example 404
, are not considered as a failure by the function, that will return TRUE
on such cases. For example, here is what happens if we send a request to “http://www.google.com/notfound”:
curl_setopt($handler, CURLOPT_URL, "http://www.google.com/notfound");
var_dump(curl_exec($handler));
bool(true)
Closing a session: curl_close
Once we finish working with our session, we must remember to close it, using the curl_close
function. The function takes the handler returned by curl_init
as its only argument and returns no values:
curl_close($handler);
A POST request example
The request we sent above was a simple GET
request. How can we send a POST
request instead? The process requires some additional steps, but nothing to worry about. First we can define the data to include in the request as an associative array:
$post_data = ["fist_name" => "Luke", "last_name" => "skywalker"];
We can then proceed to create a session and set the needed options:
$handler = curl_init("http://httpbin.org/post");
$options = [CURLOPT_POST => true, CURLOPT_POSTFIELDS => $post_data];
We used two new options, CURLOPT_POST
and CURLOPT_POSTFIELDS
. The former, set to true, is needed in order for cURL
to perform a POST
request; the latter, instead, is used to set the actual data to pass in the request. As request endpoint we used the http://httpbin.org/post
URL, which is provided by the httpbin service, and is dedicated to test POST
requests. Let’s pass the options and execute our request:
curl_setopt_array($handler, $options);
curl_exec($handler);
The response returned by the service, is the description of the request we sent, here it is:
{ "args": {}, "data": "", "files": {}, "form": { "fist_name": "Luke", "last_name": "skywalker" }, "headers": { "Accept": "*/*", "Content-Length": "255", "Content-Type": "multipart/form-data; boundary=------------------------0807f66ddf7311da", "Host": "httpbin.org" }, "json": null, "origin": "xx.xxx.xx.xxx, xx.xxx.xx.xxx", "url": "https://httpbin.org/post" }
As you can notice, since we used an array to provide the request data ($post_data
) the Content-Type
header of our request was automatically set to multipart/form-data
. With the same technique, we can also send json-encoded
data: all we need to do is to encode the data as json
and change the Content-Type
and Content-Length
headers. Here is the code:
$post_data = json_encode(["first_name" => "Luke", "last_name" => "Skywalker"]);
$options = [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $post_data,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Content-Length: ' . strlen($post_data)
]
];
$handler = curl_init("http://httpbin.org/post");
curl_setopt_array($handler, $options);
curl_exec($handler);
This time, the content of the response is:
{ "args": {}, "data": "{\"first_name\":\"Luke\",\"last_name\":\"Skywalker\"}", "files": {}, "form": {}, "headers": { "Accept": "*/*", "Content-Length": "39", "Content-Type": "application/json", "Host": "httpbin.org" }, "json": { "last_name": "Skywalker", "name": "Luke" }, "origin": "xx.xxx.xx.xxx, xx.xxx.xx.xxx", "url": "https://httpbin.org/post" }
We can now close our session:
curl_close($handle);
Conclusions
In this tutorial we learn how to use the PHP cURL extension. We saw how to install the extensions in the most commonly used distributions, and the basic steps to perform GET
and POST
requests, using the curl_init, curl_setopt, curl_exec and curl_close functions, respectively used to initialize a session, set the available options, execute the session and close it. You may also be interested in our series of articles about performing HTTP requests with python.