ckportfolio.com - cURL: Basic Usage

cURL: Basic Usage

Introduction

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.

Request Methods

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 Method

To 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 Method

In 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)
}

Additional Considerations

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:

  • PHP's documentation features a complete list of available options for cURL.
  • Designed for today's popular programming languages, Stripe's API documentation is one of many thoroughly constructed web service documentations.
  • There may be a few documentations that only accommodate command-line cURL. cURL commands can be easily converted into the PHP format using curl-to-PHP.
Fin