Download the PHP package blockchainofthings/catenis-api-client without Composer

Catenis API PHP Client

This library is used to make it easier to access the Catenis API services from PHP applications.

This current release (6.0.1) targets version 0.12 of the Catenis API.

Installation

The recommended way to install the Catenis API PHP client is using Composer.

To add Catenis API Client as a dependency to your project, follow these steps:

1. Add the following repository entries to your composer.json file:

2. Then add the required dependencies by either:

Issuing the following command:

Or editing the composer.json file directly:

Note: normally, only the blockchainofthings/catenis-api-client package would need to be listed. However, since this release of the Catenis API library depends on special patched versions of the other three packages, they also need to be listed here.

Usage

Just include Composer's vendor/autoload.php file and Catenis API Client's components will be available to be used in your code.

Instantiate the client

Optionally, the client can be instantiated without passing both the $deviceId and the $apiAccessSecret parameters or setting them to null as shown below. In this case, the resulting client object should be used to call only public API methods.

Constructor options

The following options can be used when instantiating the client:

• host [string] - (optional, default: 'catenis.io') Host name (with optional port) of target Catenis API server.
• environment [string] - (optional, default: 'prod') Environment of target Catenis API server. Valid values: 'prod', 'sandbox'.
• secure [boolean] - (optional, default: true) Indicates whether a secure connection (HTTPS) should be used.
• version [string] - (optional, default: '0.12') Version of Catenis API to target.
• useCompression [boolean] - (optional, default: true) Indicates whether request/response body should be compressed.
• compressThreshold [integer] - (optional, default: 1024) Minimum size, in bytes, of request body for it to be compressed.
• timeout [float|integer] - (optional, default: 0, no timeout) Timeout, in seconds, to wait for a response.
• eventLoop [React\EventLoop\LoopInterface] - (optional) Event loop to be used for asynchronous API method calling mechanism.
• pumpTaskQueue [boolean] - (optional, default: true) Indicates whether to force the promise task queue to be periodically run.
• pumpInterval [integer] - (optional, default: 10) Time, in milliseconds, specifying the interval for periodically running the task queue.

Asynchronous method calls

Each API method has an asynchronous counterpart method that has an Async suffix, e.g. logMessageAsync.

The asynchronous methods return a promise, and, when used with an event loop, can have their result processed in a asynchronous way.

To be used with an event loop, pass the event loop instance as an option when instantiating the ApiClient object.

Example of processing asynchronous API method calls.

Note: for promises to be asynchronously resolved, the promise task queue should be periodically run (i.e. \GuzzleHttp\Promise\queue()->run()). By default, the Catenis API PHP client will run the promise task queue every 10 milliseconds. To set a different interval for running the promise task queue, pass the optional parameter pumpInterval with an integer value corresponding to the desired time in milliseconds when instantiating the Catenis API PHP client (e.g. 'pumpInterval' => 5). Alternatively, to avoid that the promise task queue be run altogether, pass the optional parameter pumpTaskQueue set to false when instantiating the client (i.e. 'pumpTaskQueue' => false). In that case, the end user shall be responsible to run the promise task queue.

To force the returned promise to complete and get the data returned by the API method, use its wait() method.

Returned data

On successful calls to the Catenis API, the data returned by the client library methods only include the data property of the JSON originally returned in response to a Catenis API request.

For example, you should expect the following data to be returned from a successful call to the logMessage method:

Logging (storing) a message to the blockchain

Passing the whole message's contents at once

Passing the message's contents in chunks

Logging message asynchronously

Sending a message to another device

Passing the whole message's contents at once

Passing the message's contents in chunks

Sending message asynchronously

Reading a message

Retrieving the whole read message's contents at once

Retrieving the read message's contents in chunks

Reading message asynchronously

Retrieving information about a message's container

Retrieving information about a message's origin

Retrieving asynchronous message processing progress

Note: see the Logging message asynchronously, Sending message asynchronously and Reading message asynchronously sections above for more complete examples.

Listing messages

Note: the parameters taken by the listMessages method do not exactly match the parameters taken by the List Messages Catenis API method. Most of the parameters, except for the last two (limit and skip), are mapped to keys of the first parameter ($selector) of the listMessages method with a few singularities: parameters fromDeviceIds and fromDeviceProdUniqueIds and parameters toDeviceIds and toDeviceProdUniqueIds are replaced with keys fromDevices and toDevices, respectively. Those keys accept for value an indexed array of device ID associative arrays, which is the same type of associative array taken by the first parameter ($targetDevice) of the sendMessage method. Also, the date keys, startDate and endDate, accept for value not only strings containing ISO 8601 formatted dates/times but also DateTime objects.

Issuing an amount of a new asset

Issuing an additional amount of an existing asset

Transferring an amount of an asset to another device

Creating a new non-fungible asset and issuing its (initial) non-fungible tokens

Passing non-fungible token contents in a single call

Passing non-fungible token contents in multiple calls

Doing issuance asynchronously

Issuing more non-fungible tokens for a previously created non-fungible asset

Passing non-fungible token contents in a single call

Passing non-fungible token contents in multiple calls

Doing issuance asynchronously

Retrieving the data associated with a non-fungible token

Doing retrieval synchronously

Doing retrieval asynchronously

Transferring a non-fungible token to another device

Doing transfer synchronously

Doing transfer asynchronously

Retrieving information about a given asset

Getting the current balance of a given asset held by the device

Listing assets owned by the device

Listing assets issued by the device

Retrieving issuance history for a given asset

Note: the parameters of the retrieveAssetIssuanceHistory method are slightly different from the ones taken by the Retrieve Asset Issuance History Catenis API method. In particular, the date parameters, $startDate and $endDate, accept not only strings containing ISO 8601 formatted dates/times but also DateTime objects.

Listing devices that currently hold any amount of a given asset

Exporting an asset to a foreign blockchain

Estimating the export cost in the foreign blockchain's native coin

Doing the export

Migrating an asset amount to a foreign blockchain

Estimating the migration cost in the foreign blockchain's native coin

Doing the migration

Reprocessing a (failed) migration

Getting asset export outcome

Getting asset migration outcome

Listing exported assets

Note: the parameters taken by the listExportedAssets method do not exactly match the parameters taken by the List Exported Assets Catenis API method. Most of the parameters, except for the last two (limit and skip), are mapped to keys of the first parameter ($selector) of the listExportedAssets method with a few singularities: the date keys, startDate and endDate, accept for value not only strings containing ISO 8601 formatted dates/times but also DateTime objects.

Listing asset migrations

Note: the parameters taken by the listAssetMigrations method do not exactly match the parameters taken by the List Asset Migrations Catenis API method. Most of the parameters, except for the last two (limit and skip), are mapped to keys of the first parameter ($selector) of the listAssetMigrations method with a few singularities: the date keys, startDate and endDate, accept for value not only strings containing ISO 8601 formatted dates/times but also DateTime objects.

Listing system defined permission events

Retrieving permission rights currently set for a specified permission event

Setting permission rights at different levels for a specified permission event

Checking effective permission right applied to a given device for a specified permission event

Retrieving identification information of a given device

Listing system defined notification events

Notifications

The Catenis API PHP client makes it easy for receiving notifications from the Catenis system by embedding a WebSocket client. All the end user needs to do is open a WebSocket notification channel for the desired Catenis notification event, and monitor the activity on that channel.

Notifications require that an event loop be used. You should then pass the event loop instance as an option when instantiating the ApiClient object, in the same way as when using the asynchronous API methods.

Note: if no event loop instance is passed when instantiating the ApiClient object, an internal event loop is created. However, in that case, notifications will only be processed once the application is shut down (and the event loop is finally run).

Receiving notifications

Instantiate WebSocket notification channel object.

Add listeners.

Note: the data argument of the notify event contains the deserialized JSON notification message (a stdClass instance) of the corresponding notification event.

Open notification channel.

Note: the open() method of the WebSocket notification channel object works in an asynchronous way, and as such it returns a promise like the asynchronous API methods do.

Close notification channel.

Error handling

Error conditions are reported by means of exception objects, which are thrown, in case of synchronous methods, or passed as an argument, in case of asynchronous methods.

API method exceptions

The following exceptions can take place when calling API methods:

• CatenisClientException - Indicates that an error took place while trying to call the Catenis API endpoint.
• CatenisApiException - Indicates that an error was returned by the Catenis API endpoint.

Note: these two exceptions derive from a single exception, namely CatenisException.

The CatenisApiException object provides custom methods that can be used to retrieve some specific data about the error condition, as follows:

• getHttpStatusCode() - Returns the numeric status code of the HTTP response received from the Catenis API endpoint.

• getHttpStatusMessage() - Returns the text associated with the status code of the HTTP response received from the Catenis API endpoint.

• getCatenisErrorMessage() - Returns the Catenis error message returned from the Catenis API endpoint.

Usage example:

Expected result:

WebSocket notification exceptions

The following exceptions can take place when opening a WebSocket notification channel:

• OpenWsConnException - Indicates that an error took place while establishing the underlying WebSocket connection.
• WsNotifyChannelAlreadyOpenException - Indicates that the WebSocket notification channel (for that device and notification event) is already open.

Note: these two exceptions derive from a single exception, namely WsNotificationException, which in turn also derives from CatenisException.

Usage example:

Catenis API Documentation

For further information on the Catenis API, please reference the Catenis API Documentation.

License

This library is released under the MIT License. Feel free to fork, and modify!

Copyright © 2018-2022, Blockchain of Things Inc.