This is a brief guide on how to integrate your PHP website with Kumulos. For a slightly more worked example, please refer to the MugShot PHP cookbook.

Requirements

Here are the requirements for your PHP installation:

  • PHP 5.2 or greater
  • cURL

To get started, go ahead and download Kumulos’ PHP Bindings.

Calling an API Method

<?php
// Include the library
require_once 'path/to/libKumulos.php';

// Create an instance of the Kumulos API class
// API key and secret key are found on the application's dashboard
$k = new kAPI('yourAPIKey', 'yourSecretKey');

try {
    // Your input parameters
    $params = array('foo' => 'bar');
    // The methodAlias can be seen on the application's API method tab
    $result = $k->call('methodAlias', $params);
}

// If you don't catch this, it will trigger the default exception handler on error
catch (kAPIException $e) {
    echo $e->getMessage();
    echo 'Server response:';
    var_dump($e->serverResponse);
}

// Do something with the result...

Handling Errors

By default, the kAPI class will throw a kAPIException when an error occurs with the request. If you’d rather not catch exceptions, you can pass a third parameter to the constructor like so:

$k = new kAPI('yourAPIKey', 'yourSecretKey', false);

That will make the Kumulos PHP SDK trigger errors instead of throwing exceptions.

Data Fields

When you’re calling Kumulos to send data to a data field, you need to base64 encode the data before passing the parameter to kAPI::call. You can use PHP’s base64_encode function to encode the data for you.

Similarly, when you receive data from a Kumulos data field, it will be base64 encoded and require being decoded with base64_decode to access the original data.