PHP API

If you are working in a PHP environment we provide a package that provides library functions to make interacting with the CloudTables API as simple as a class constructor and method call. Using the library you can easily embed data sets securely into your pages, get information about data sets and the data of a specified dataset.

Installing

Our PHP libraries to embed CloudTables are available from the Composer package manager, or can be used directly with a regular PHP require.

Composer

The CloudTables libraries are available as the cloudtables/client package on Composer and can be installed for your project using:

composer require cloudtables/client

Using a regular require 'vendor/autoload.php'; will then automatically load the CoudTables API class when required by your code.

Direct require

Alternatively, if you prefer to include the PHP file directly (i.e. you aren't using Composer), the source file can be obtained from our source repo. The Api.php file should then be included in your PHP using require 'path/to/Api.php';.

Use

Once available into your application, an instance can be created using:

$api = new CloudTables\Api('{apiKey}', [
	clientId => 'Unique client id', // Client id (e.g. a login id) - optional
	clientName => 'Name',           // Client's name - optional
	domain => '{ip-or-hostname}',   // Your CloudTables host
	ssl => false                    // Disable https
]);

Where:

• {apiKey} should be replaced by the API key that you want to use for the access.
• The clientId and clientName parameters in the configuration object are optional, but we strongly recommend they are used when integrating with your own login system as it allows the identification of each client's actions in CloudTables' auditing features. Typically the clientId would be set to your login system's user id and clientName the user's username or full name.

• {ip-or-hostname} is the access address configured for your CloudTables install.

A new Api instance should be created for each access request, as it will cache and reuse the access token if one is required.

Embedding data sets

There are two methods provided by the library which can be used to embed a data set into your HTML page. The end result is a <script> tag which includes an access token. That can then be inserted into your HTML using a variable, a template or another method depending on how you are generating your HTML.

Automatic script tag

The scriptTag method can be used to get an access token (based on the initialisation options) for a data set, and will return a string that contains the full <script> tag that should be inserted into your HTML:

$script = $api->scriptTag('{data-set-id}');

Where:

• {data-set-id} is the ID of the data set you wish to embed into the page. The data set ID can be found in the Inspector for the data set on the Data tab.

Custom script tag

Alternatively, you can also build your own <script> tag based on a token:

$token = $api->token();
$script = "
	<script
		src='https://ip-or-hostname/io/loader/{data-set-id}/table/d'
		data-token='$token'
	></script>
";

Demonstration video

In the following video Colin walks through a demonstration of installing and using the CloudTables PHP library.

API Reference

Constructor

Creates a new instance of the CloudTables API libraries.

new CloudTables\Api(string $key, $options)

• Parameters:
  1. string - The API key to be used
  2. object - Object of optional parameters:
     • string clientId - A unique id for the client accessing the table on your system. While this is optional it is a recommended parameter as it is useful for tracking requests in CloudTables’ analytics.
     • string clientName - A label that can help identify a user - e.g. a name or e-mail address.
     • condition: array | object - Condition(s) to apply to data being fetched. Please see the embedding conditions documentation for full details. Requires cloudtables-api 1.1 or newer.
     • string duration - Access token’s idle time out (defaults to 20 minutes).
     • string[] roles - The name of the role that should be used for the generated access token (if assigned to the API key - if the role is not available for the API key no access will be granted). If not provided then all roles available to the API key will be used.
     • string role - Per roles but for a single role only.
     • boolean secure - Disallow (true), or allow (false) self-signed certificates
     • boolean ssl - Enable (true), or disable (false) SSL / HTTPS
• Returns: API instance

Methods

data

Get the data and columns for a given dataset.

->data(string $dataset): Array

• Parameters:
  1. string - ID of the data set to get the data of. See the Data page for the data set to get its ID, or use the ->datasets() method.
• Returns: Object containing data and columns arrays. Please refer to the API documentation for a full description of the structure returned.

datasets

Get summary information about the available datasets (note that the roles applied in the constructor can restrict access so certain data sets will not be shown).

->datasets(): Array

• Returns: Array containing information about the available data sets. Please refer to the API documentation for a full description of the structure returned.

token

Get an access token. Note that this value is cached per API instance. It will only be obtained from the CloudTables server's once.

->token(): string

• Returns: Access token to be used with the <script> tag to access a data set.

scriptTag

Get a <script> tag for a specific dataset to be displayed as a table. Insert this script tag where you want the table to appear in your HTML.

->scriptTag(string $dataset, string $style = 'd'): string
->scriptTag(string $token, string $dataset, string $style = 'd'): string

• Parameters:
  1. token: string - Secure access token (from .token()). Optionally this parameter need not be given, in which case the token is retrieved automatically.
  2. dataset: string - ID (UUID) of the dataset to be shown
  3. style: string - The styling framework to use for this table. Can be one of:
     • d - Default
     • auto - Auto detect
     • bs - Bootstrap 3
     • bs4 - Bootstrap 4
     • dt - CloudTables / DataTables default styling
     • zf - Zurb Foundation
     • ju - jQuery UI
     • se - Semantic UI
     • no - No styling
• Returns: <script> tag to use.

Source

Our API libraries for CloudTables are open source under the MIT license. The PHP source is available here and pull requests or suggestions for it are welcome.