SDK (PHP)

The purpose of the DXCloud SDK is to simplify the usage of our REST API. The explicit construction of the required JSON objects may be, in certain cases, a tedious task so to the main goal of our SDK is to encapsulate the required procedures in a few convenience methods.

By the time being we only offer a PHP version although we plan to offer versions in different programming language in the near future. By the way, if you are interested in helping us to build an SDK in your preferred language, please, contact us.

In the following we will offer a brief explanation of the provided methods but you may also refer to the general documentation of the API to obtain a better grasp of the full breadth of capabilities offered by our REST API.

Installation

The recommended way to install the DXCloud SDK is through Composer.

You may use our Packagist package by simply running:

composer require docxpresso/dxcloud

Or download the full packege from our GIT repository and run:

composer install

in the folder where you unzipped the package (it should contain a composer.json with all the required info). In this case you should also need to include an explicit call to the library files.

Basic usage

In general terms you have to follow these steps:

• Include the required SDK files via the autoloader generated by composer.
• Authenticate using the API Key (that you can obtain after login into your account).
• Request an access token.
• Create a document object.
• Provide the required data: template, merging fields, ...
• Do the request to the REST API (data plus access token).

This example illustrates the required procedure:

<?php
//path_to_vendor is either the full or relative path to the vendor folder
require_once('path_to_vendor/vendor/autoload.php');
use DXCloud\SDK as SDK;
//call the constructor including your API key
$DX = new SDK\DXClient('apikey');
//get the required access token. Beware that the token expires after an hour
$DX->generateAccessToken();
//create the document giving the path of the template or a base64 encoded string
$document = $DX->createDocument('path_to_template.odt');
//replace a variable value (methods can be chained)
$document->replaceText('company', ['Docxpresso'])
         ->replaceText('address', ['Arturo Baldasano 16, <strong>SPAIN</strong>']);
//render the rdocument by making a request to the REST API
$document->render('saveAndDownload', 'pdf', 'folder/filename.pdf');                    

Or if you just want to convert a document to a different format:

<?php
//path_to_vendor is either the full or relative path to the vendor folder
require_once('path_to_vendor/vendor/autoload.php');
use DXCloud\SDK as SDK;
//call the constructor including your API key
$DX = new SDK\DXClient('apikey');
//get the required access token. Beware that the token expires after an hour
$DX->generateAccessToken();
//converts the provided document and processes it to be saved with target name 
//or as a string
$document = $DX->convert('source', 'target', 'saveAndDownload');           

General comments

Before getting into the nitty-gritty details a few comments are due:

• Methods may be chained.
• All instructions are carried out in the following order:
  • Remove methods.
  • Clone methods.
  • Replace methods.
  • Within any of the previous groups following the given order.
• Whenever possible you may reuse the access tokens (that remain valid for an hour) to minimize the number of calls to the REST API.

SDK Methods

We group the available methods if 5 different logical categories:

• General purpose: that are used for document generation.
• Replace data: that are used for inserting data in a given template.
• Remove blocks: that are used for removing blocks of content from the template.
• Clone blocks: that are used for cloning blocks of content from the template.
• Auxiliary methods: that are used to configure the logs and get error info among others.

General purpose

generateAccessToken

createDocument

render

convert

Replace data

In general terms (but in the replaceText method) the variables will be identified by name and/or match, i.e. leaving the name empty the match will determine the element to be replaced, if both are given both conditions would be taken into account.

replaceText

replaceParagraph

replaceTable

replaceListItem

replaceImage

replacePieChart

replaceGenericChart

Remove blocks

The following methods allow for the removal of blocks of content that contain a "needle" or search term. This needle does not need to be a variable although it may show convenient to do so.

Once again one may use the needle and/or match option to select a block of content by its text content and/or position in the document.

removeText

removeBookmark

removeParagraph

removeList

removeListItem

removeTable

removeTableRow

removeImage

removeChart

removeTextbox

removeHeading

Clone blocks

The following methods allow for the cloning of blocks of content that contain a "needle" or search term. This needle does not need to be a variable although it may show convenient to do so.

Once again one may use the needle and/or match option to select a block of content by its text content and/or position in the document.

cloneBookmark

cloneParagraph

cloneList

cloneListItem

cloneTable

cloneTableRow

cloneImage

cloneChart

cloneTextbox

cloneHeading

Auxiliary methods

The following methods may let you set some general config parameters and help you in the handling of errors.

getError

getData

setLogConfig

Error handling and logging

Whenever possible the render method tries to manage automatically "recoverable errors":

• Error code 1: (incorrect authorization) the SDK makes an automatic request for a new token and resends the petition after one second.
• Error code 10: (service temporarily out of service) this may be caused by a temporary overload in the API REST endpoint so the system retries once to send a request after 5 seconds.

All other errors should be captured and processed by the user. In case of error the render method returns false, in case you need to know the error details you may call the getError() method on the output of the render method:

$document->render('saveAndDownload', 'pdf', 'folder/filename.pdf');
if ($document === false){
    $error = $document->getError();
    //parse the JSON and do whatever you want to handle it
    $errorCode = $error->code;
    $errorMessage = $error->error;
}         

You may check the full list of response errors in here.

Logs

The SDK logs all interaction with the REST API endpoint in a text file that can be found in src/log/dxcloud.log or wherever you have decided with the help of the setLogPath method, so make sure that that path is writable by the user running the scripts.

There are 3 levels of notifications:

• info: purely informative.
• warning: an error that the SDK tries to "recover automatically".
• error: a non-recoverable error.