Read and Write Data on IBM Cloudant with PHP

IBM Cloudant is a fully-managed, distributed database that runs as a service on IBM Cloud. It is based on Apache CouchDB (although it is not open source itself) and can be accessed using a standard HTTP REST API.

If you’re building an application that uses IBM Cloudant as a data store, this REST API makes it easy to interact with the database service from any language that has an HTTP client library, even if that language doesn’t have a native driver or SDK for IBM Cloudant.

To illustrate how easy this is, I’ll provide a few examples of how to connect to, and use, an IBM Cloudant database service from PHP using the Guzzle PHP HTTP client.

NOTE: Before proceeding, deploy an IBM Cloudant service and obtain an access token for the service. Note the values of the apikey, host and access_token fields.

First, install Guzzle with Composer:

composer require guzzlehttp/guzzle:^7.0

Then, start with a simple script which creates an HTTP client with the appropriate Authorization header and sends a PUT request to the service endpoint to create a new, empty IBM Cloudant database.

<?php
// load required classes
require 'vendor/autoload.php';

use GuzzleHttp\Client;

// configure access token
$token = 'YOUR-ACCESS-TOKEN-HERE';

// configure public endpoint
$url = 'YOUR-CLOUDANT-HOSTNAME-HERE';

// configure client
$client = new Client([
    'base_uri' => $url,
    'headers' => ['Authorization' => 'Bearer ' . $token]
]);

// create database
try {
    $db = $client->request('PUT', '/mydb');
    print_r($db->getBody()->getContents());
}  catch (Exception $e) {
    echo 'FAILED: ' . $e->getMessage();
}

Save and execute this script from the command line. Here’s an example of the output:

{"ok":true}

If you launch the IBM Cloudant dashboard from your IBM Cloud dashboard, you should see the new, empty database.

alt

Here’s another example, this one sending a POST request to the service endpoint to create a document. The body of the POST request is a JSON structure representing the document to be created in the IBM Cloudant database.

<?php
// load required classes
require 'vendor/autoload.php';

use GuzzleHttp\Client;

// configure access token
$token = 'YOUR-ACCESS-TOKEN-HERE';

// configure public endpoint
$url = 'YOUR-CLOUDANT-HOSTNAME-HERE';

// configure client
$client = new Client([
    'base_uri' => $url,
    'headers' => ['Authorization' => 'Bearer ' . $token]
]);

// create document
try {
    $doc = $client->request('POST', '/mydb', [
        'json' => [
            'name' => 'eggs',
            'quantity' => '7'
        ]
    ]);
    print_r($doc->getBody()->getContents());
}  catch (Exception $e) {
    echo 'FAILED: ' . $e->getMessage();
}

Save and execute this script from the command line. Here’s an example of the output:

{"ok":true,"id":"0fb918aa44eb42ef022a3c99f5a35b71,"rev":"1-05caccd33e5a19c88ed4c687d86abe51"}

If you check the IBM Cloudant dashboard, you should see the new document in the database.

alt

Finally, to wrap this up, let’s delete the document.

<?php
// load required classes
require 'vendor/autoload.php';

use GuzzleHttp\Client;

// configure access token
$token = 'YOUR-ACCESS-TOKEN-HERE';

// configure public endpoint
$url = 'YOUR-CLOUDANT-HOSTNAME-HERE';

// configure client
$client = new Client([
    'base_uri' => $url,
    'headers' => ['Authorization' => 'Bearer ' . $token]
]);

// get document revision id
// delete document
try {
    $doc = $client->request('GET', '/mydb/0fb918aa44eb42ef022a3c99f5a35b71');
    $rev = json_decode($doc->getBody()->getContents())->_rev;
    $doc = $client->request('DELETE', '/mydb/0fb918aa44eb42ef022a3c99f5a35b71?rev=' . $rev);
    print_r($doc->getBody()->getContents());
}  catch (Exception $e) {
    echo 'FAILED: ' . $e->getMessage();
}

To delete a document from IBM Cloudant, you first need to obtain the document’s revision number. This is done by sending a GET request to the service endpoint referencing the document identifier. The response includes the document revision number. This revision number is then included in the DELETE request.