Documentation

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

Requests the access token required for generating/converting documents with DXCloud REST API. The token is stored internally so you do not need to do anything else. Beware that the token expires after an hour so if your script may last longer you should request it again before it expires or do it after processing the associated error response.

public generateAccessToken()

Parameters
  • No parameters.

createDocument

Creates a "document" from a template where we can start parametrizing all merging data.

public createDocument($template)

Parameters
  • $template (type: string). The path to the template file (.odt) or a base64 encoded string generated from a template file.

render

Calls the REST API to generate the document out of template and all merging data provided.

public render($output, $format, $name)

Parameters
  • $output (type: string). This parameter determines what are we going to do with the resulting document. Options are:
    • 'file': saves the respone as a file with the provided name.
    • 'string': returns the document as a base64 encoded string.
    • 'browser': sends directly the document to the browser. If the browser does not recognizes the mime type it will (normally) download it.
    • 'download': downloads it directly with the provided name.
    • 'saveAndDownload': saves it to the file system and sends it to the browser to be downloaded.
  • $format (type: string). The format of the requested documents. The available options are: pdf, docx, doc, odt and rtf.
  • $name (type: string). The name given to the requested document (it may be left empty if the selected output is string).

convert

Calls the REST API to convert a document into a diffrent format.

You may convert from docx, doc, odt and rtf into pdf, docx, doc, odt and rtf.

public convert($source, $target, $output)

Parameters
  • $source (type: string). The path to the document to be converted. The available source documents formats are: docx, doc, odt and rtf.
  • $target (type: string). The name given to the requested document. The available target documents formats are: pdf, docx, doc, odt and rtf.
  • $output (type: string). This parameter determines what are we going to do with the resulting document. Options are:
    • 'file': saves the respone as a file with the provided name.
    • 'string': returns the document as a base64 encoded string.
    • 'browser': sends directly the document to the browser. If the browser does not recognizes the mime type it will (normally) download it.
    • 'download': downloads it directly with the provided name.
    • 'saveAndDownload': saves it to the file system and sends it to the browser to be downloaded.

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

This method replaces a variable by the provided text or HTML code. Beware that you use HTML and the blockVariable option is set to false (default value) only "inline HTML tags" will be rendered.

The replacement algorithm follows a cyclic rule, i.e. if there are more variable appearances than values provided the array "rewinds" so if only one value is provided it will be used for all instances of the variable and so long so forth.

public replaceText($varName, $varValues, $options = array())

Parameters
  • $varName (type: string). The name of the variable to be replaced.
  • $varValues (type: array). An array with the replacement values
  • $options (type: array). An array with the following keys and values:
    • html (type: boolean) if true the string will be parsed as HTML (default is true).
    • parse-line-breaks (type: boolean) if true parses line breaks (default is false).
    • block-type (type: boolean) if true the containing paragraph will be completely replaced by the provided value (default is false).
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

replaceParagraph

This method allows to clone a paragraph as many times as needed to acomodate the variable values supplied, i.e. if we are providing more than one value to a given variable the containing paragraph will be cloned as many times as needed.

public replaceParagraph($data, $options = array())

Parameters
  • $data (type: array). an array of arrays where the key must correspond to the variable name and the value should be itself an array with the values that should be fed, i.e. array('var_1' => array('val1', 'val2')), 'var2' => array('val3', 'val4'))
  • $options (type: array). An array with the following keys and values:
    • html (type: boolean) if true the string will be parsed as HTML (default is true).
    • parse-line-breaks (type: boolean) if true parses line breaks (default is false).
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

replaceTable

This method allows to clone a group of table rows as many times as needed to acomodate the variable values supplied, i.e. if we are providing more than one value to a given variable the group of rows will be cloned as many times as needed.

To better understand the meaning of "group of rows" take into account that Docxpresso will group logically all rows within a table the include a variable within it. In the case of nested tables the grouping will be done within each table so Docxpresso will not group variables within a "subtable". Although this may result a little complex to grasp to start with it offers great flexibility when creating complex content.

public replaceTable($data, $options = array())

Parameters
  • $data (type: array). an array of arrays where the key must correspond to the variable name and the value should be itself an array with the values that should be fed, i.e. array('var_1' => array('val1', 'val2')), 'var2' => array('val3', 'val4'))
  • $options (type: array). An array with the following keys and values:
    • html (type: boolean) if true the string will be parsed as HTML (default is true).
    • parse-line-breaks (type: boolean) if true parses line breaks (default is false).
    • block-type (type: boolean) if true the containing paragraph will be completely replaced by the provided value (default is false).
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

replaceListItem

This method clones a list item as many times as needed in order to replace all values provided

public replaceListItem($varName, $varValues, $options = array())

Parameters
  • $varName (type: string). The name of the variable to be replaced.
  • $varValues (type: array). An array with the replacement values
  • $options (type: array). An array with the following keys and values:
    • html (type: boolean) if true the string will be parsed as HTML (default is true).
    • parse-line-breaks (type: boolean) if true parses line breaks (default is false).
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

replaceImage

This method replaces an image that has been tagged with an alt text within the template.

You may use a path for the new image or directly provide a base64 encoded image, i.e. data:image/png;base64,iVBORw0K… (https://en.wikipedia.org/wiki/Data_URI_scheme).

If we leave empty the width and height of the image, the system will use that of the provided image.

public replaceImage($varName, $varValues, $options = array(), $width = '', $height = '')

Parameters
  • $varName (type: string). The name of the alt text to be searched for.
  • $varValues (type: array). An array with the replacement values/paths.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).
  • $width (type: string). The width of the image in px, pt, cm or in. If not provided the width of the provided image will be used.
  • $height (type: string). The height of the image in px, pt, cm or in. If not provided the height of the provided image will be used.

replacePieChart

This method replaces the chart data for pie and doughnut type charts with the given name in the corresponding alt text.

If the number of data points is larger that the one used in the placeholder chart, additional data points will be ignored, so make sure that the associated template chart can accomodate all data. If the number of data points is smaller the template chart will be reorder accordingly.

public replacePieChart($varName, $varValues, $options = array())

Parameters
  • $varName (type: string). The name of the alt text to be searched for.
  • $varValues (type: array). An associative array containing the category names as keys, i.e. ['first' => 20, 'second' => 30]
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.

replaceGenericChart

This method replaces the chart data for generic charts (bar, columns, radar, ...)with the given name in the corresponding alt text.

If the number of data points is larger that the one used in the placeholder chart, additional data points will be ignored, so make sure that the associated template chart can accomodate all data. If the number of data points is smaller the template chart will be reorder accordingly.

public replaceGenericChart($varName, $varValues, $options = array())

Parameters
  • $varName (type: string). The name of the alt text to be searched for.
  • $varValues (type: array). An associative array containing the category names as keys, i.e. ["series"=>["ser 1","ser 2","ser 3"], "first"=>[1,3,58],"second"=>[18,5,8]]
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.

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

Removes the text provided as needle.

public removeText($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched and removed.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

removeBookmark

Removes the bookmark containing the provided needle in the bookmark name or if empty the provided match.

public removeBookmark($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the bookmark name.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

removeParagraph

Removes the paragraph containing the provided needle or if empty the provided match.

public removeParagraph($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the paragraph.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

removeList

Removes the (complete) list containing the provided needle or if empty the provided match.

public removeList($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the list.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

removeListItem

Removes the list item containing the provided needle or if empty the provided match.

public removeListItem($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the list item.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

removeTable

Removes the table containing the provided needle or if empty the provided match.

public removeTable($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the table.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

removeTableRow

Removes the table row containing the provided needle or if empty the provided match.

public removeTableRow($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the table row.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

removeImage

Removes the image containing the provided needle in the alt text or if empty the provided match.

public removeImage($needle = '', $options = array())

Parameters
  • $needle (type: string). The alt text to be searched for in the image alt text.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).
    • container (type: boolean) if true it also removes the parent container (default value is false).

removeChart

Removes the chart containing the provided needle in the alt text or if empty the provided match.

public removeChart($needle = '', $options = array())

Parameters
  • $needle (type: string). The alt text to be searched for in the chart alt text.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).
    • container (type: boolean) if true it also removes the parent container (default value is false).

removeTextbox

Removes the textbox containing the provided needle or if empty the provided match.

public removeTextbox($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the paragraph.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

removeHeading

Searches for a heading cotaining the provided needle, or if empty the provided match, and removes all content falling under it

public removeHeading($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the heading.
  • $options (type: array). An array with the following keys and values:
    • heading-level (type: integer) the heading level to be searched. The default value is 1.
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

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

Clones the bookmark containing the provided needle in the bookmark name or if empty the provided match.

public cloneBookmark($needle = '', $repeat, $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the bookmark name.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

cloneParagraph

Clones the paragraph containing the provided needle or if empty the provided match.

public cloneParagraph($needle = '', $repeat, $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the paragraph.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

cloneList

Clones the (complete) list containing the provided needle or if empty the provided match.

public cloneList($needle = '', $repeat, $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the list.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

cloneListItem

Clones the list item containing the provided needle or if empty the provided match.

public cloneListItem($needle = '', $repeat, $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the list item.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

cloneTable

Clones the table containing the provided needle or if empty the provided match.

public cloneTable($needle = '', $repeat, $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the table.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

cloneTableRow

Clones the table row containing the provided needle or if empty the provided match.

public cloneTableRow($needle = '', $repeat, $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the table row.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

cloneImage

Clones the image containing the provided needle in the alt text or if empty the provided match.

public cloneImage($needle = '', $repeat, $options = array())

Parameters
  • $needle (type: string). The alt text to be searched for in the image alt text.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

cloneChart

Clones the chart containing the provided needle in the alt text or if empty the provided match.

public cloneChart($needle = '', $repeat, $options = array())

Parameters
  • $needle (type: string). The alt text to be searched for in the chart alt text.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

cloneTextbox

Clones the textbox containing the provided needle or if empty the provided match.

public cloneTextbox($needle = '', $repeat, $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the paragraph.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

cloneHeading

Searches for a heading cotaining the provided needle, or if empty the provided match, and clones all content falling under it

public cloneHeading($needle = '', $options = array())

Parameters
  • $needle (type: string). The text to be searched for in the heading.
  • $repeat (type: integer). the number of times this block should be cloned.
  • $options (type: array). An array with the following keys and values:
    • heading-level (type: integer) the heading level to be searched. The default value is 1.
    • match (type: integer) if given only that match will be replaced.
    • target (type: string) possible values are document, header or footer. It defines where the variable should be searched for (default is document).

Auxiliary methods

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

getError

Returns, if any, an object with the error thrown by the render or convert methods. This object has as properties the error code and message provided by the REST API.

public getError()

Parameters
  • No parameters

getData

Returns the JSON data sent to the endpoint. This may be useful for debugging purposes.

public getData()

Parameters
  • No parameters

setLogConfig

Sets the options for logging: the level of notifications and the path to the logging file.

public setLogConfig($level = 'info', $path = '')

Parameters
  • $level (type: string). The loggin level of notification:
    • 'none': No message to be logged
    • 'info': All messages are logged: info, warning, error. This is the default value.
    • 'error': Only log error messages
  • $path (type: string). This optional parameters should be the absolute path to the desired log location and name. If not given the log is created in the library log folder: log/dxcloud.log

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.