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
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.
Parameters
getData
Returns the JSON data sent to the endpoint. This may be useful for debugging purposes.
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.