Designed as a flexible open-source tool to help developers communicate freely with different web destinations, cURL ("Client URL") has since then become an essential tool for building today's mashup ecosystem. Available as a standalone command-line tool and a software library, and PHP also benefits from cURL as we have an ability to build mashup applications using PHP-specific syntax.
The rise of mashup application signaled the end of web communication as a passive, read-only experience, as our websites now can submit user-provided data to a remote destination and manipulate its data. While there are numerous request methods common to web, GET
and POST
are two of the most frequently used request methods.
GET
MethodTo visit a website on a browser is to perform a GET
request to a remote server, download the provided page, and render on the user's screen. Using PHP, we can programmatically emulate this behaviour to download the website content for our manipulation and use:
<?
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'http://example.com/');
curl_exec($curl);
curl_close();
?>
The above code initializes an instance of cURL and requests it to connect to example.com
. Upon "executing" this request, the PHP script will automatically display the downloaded the page and closes the instance.
When building a mashup application, one may wish to prevent the immediate display of the output, and save as a string for future manipulation:
<?
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://jsonplaceholder.typicode.com/users');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($curl);
$result = json_decode($result);
echo "<pre>";
var_dump($result);
echo "</pre>";
curl_close();
?>
By setting the CURLOPT_RETURNTRANSFER
option to true
, we can prevent the downloaded text from being displayed to the user. This text is instead set to the new $result
variable, which is then converted from JSON to a PHP-compliant array as the original text is a JSON document. Thereafter, we can inspect the contents of the converted object using var_dump()
.
POST
MethodIn addition to retrieving data from a remote source, we can also submit manually generated data in order to create an entry in the database or trigger a specific action. While the requirements do differ between individual web services, they have one thing in common: they require the use of POST
method.
<?
$data = array();
$data["title"] = "Hello world";
$data["body"] = "Lorem ipsum";
$data = json_encode($data);
$header = array(
'Content-Type: application/json',
);
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://jsonplaceholder.typicode.com/posts');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
$result = curl_exec($curl);
$result = json_decode($result);
echo "<pre>";
var_dump($result);
echo "</pre>";
curl_close();
?>
In the above example using a mock endpoint, we create two additional variables:
$data
variable is responsible for hosting a JSON-version of the user-constructed array (as the web service stipulates).$header
variable is responsible for communicating the endpoint that the above data
variable contains a JSON data and should behave accordingly.In conjunction, cURL receives three additional options:
CURLOPT_POST
sets the cURL instance to use POST
request method.CURLOPT_POSTFIELDS
sets the above data
variable as the "payload" sent to the endpoint.CURLOPT_HTTPHEADER
uses the above header
variable to calibrate the cURL instance.Upon successful submission, the result
variable will display the data returned by the remote server:
object(stdClass)#1 (3) {
["title"]=>
string(11) "Hello world"
["body"]=>
string(11) "Lorem ipsum"
["id"]=>
int(101)
}
While many web services are currently evolving towards more consistent data structures, their API documentations continue to vary and require careful review prior to implementation. The links below will come in handy: