Livedocx

Usage

The Livedocx class is the entry point of the library.

It serves both as a hub to assign the mergefields with values, and as a factory to create "ready to use" other classes.

If you use the frameworks integrations provided, these are working out of the box, juste fill the config files provided to start using the library.

If you're doing it the good-ol' way here is how you instanciate the class and prepare it for use:


use Awakenweb\Livedocx\Soap;
use Awakenweb\Livedocx\Livedocx;
use Awakenweb\Livedocx\Container;


$client = new Soap\Client(\SoapClient('https://path_to_the_wsdl'));
$client->connect(USERNAME, PASSWORD);


$livedocx = new Livedocx($client, new Container());

You don't have to worry about the Container class, as you will never have to deal directly with it. It just stores the field values, the blocks and the images.

Methods

Unless explicitely stated, all parameters and return values classes are prefixed with the namespace \Awakenweb\Livedocx\.

Exceptions thrown by the classes are all prefixed by \Awakenweb\Livedocx\Exceptions

__construct($client, $container)

Exceptions: none

$client: Soap\Client
$container: Container

Create an instance of the Livedocx class.

assign($key, $value)

Exceptions: ContainerException

$key: string|Block|array
$value: string|Image

Assign a value to a mergefield.

This method accepts different type of parameters:

$livedocx->assign('fieldname', 'fieldvalue');
$livedocx->assign(array('fieldname'=>''value', 'otherfield'=>'other value'));
$livedocx->assign(BLOCK);
$livedocx->assign('imagename', IMAGE);

If a different type of value is provided, a ContainerException will be thrown

createBlock()

Exceptions: none

Create a new Block instance

createDocument()

Exceptions: none

Create a new Document instance

createImage()

Exceptions: none

Create a new Image instance

createLocalTemplate()

Exceptions: none

Create a new Templates\LocalTemplate instance

createRemoteTemplate()

Exceptions: none

Create a new Templates\RemoteTemplate instance

prepare()

Exceptions: DeclarationException

Merge all the fields with their real value and return an instance of Document.

If an error occurs while actually sending the data to the webservice, a DeclarationException will be thrown.

Templates

Usage

Both local and remote templates are used to manipulate template files. You can upload and download templates to and from Livedocx servers, as well as getting many metadata about them.

Only common methods between the two types of templates will be explained here. For more specific-templates related methods, read the following articles.

A Template does class exists, but is abstract. You have to instanciate either Templates\LocalTemplate or Templates\RemoteTemplate to manipulate templates.

$template = $livedocx->createLocalTemplate();


$template->setName('MyTemplate.docx', '/home/me/myfolder/')
         ->setAsActive();

Methods

getAcceptedTemplateFormats()

Exceptions: Templates\StatusException

Get a list of all accepted file formats for file uploads.

If an error occurs while obtaning the list, a Templates\StatusException will be thrown.

getAvailableFonts()

Exceptions: Templates\StatusException

Get a list of all accepted fonts that you can use in your templates.

If an error occurs while obtaning the list, a Templates\StatusException will be thrown.

ignoreAllSubTemplates($state)

Exceptions: Templates\IgnoreException

$state: boolean

Enable or disable the possibility to ignore subtemplates included into your main template.

If an error occurs while sending the data, a Templates\IgnoreException will be thrown.

ignoreListOfSubTemplates($list)

Exceptions: Templates\InvalidException, Templates\IgnoreException

$list: array

Define a list of subtemplates to ignore while generating the final document.

If an error occurs while sending the list a Templates\IgnoreException will be thrown.

If you don't provide an array as parameter, a Templates\InvalidException will be thrown.

listAll()

Exceptions: Templates\StatusException

Get a list of all already uploaded templates on Livedocx service

If an error occurs while obtaning the list, a Templates\StatusException will be thrown.

Local Templates

Usage

Local templates are the files present on your own server. This class is especially useful to upload these files to Livedocx.

$template = $livedocx->createLocalTemplate();


$template->setName('MyTemplate.docx', '/home/me/myfolder/');
         ->upload();

Methods

getContents()

Exceptions: FileExistsException

Return the contents of the file as a single string

If the file provided does not exist or is not readable, a FileExistsException will be thrown.

getFormat($fullname)

Exceptions: FileExistsException

$fullname string

Return the format of the file identified by its full name as a string.

If the file provided does not exist or is not readable, a FileExistsException will be thrown.

getName($full)

Exceptions: none

$full: boolean optional

Return the name of the file as a string.

If the $full argument is provided, the complete path to the file is also returned.

setAsActive()

Exceptions: FileExistsException, Templates\ActiveException

Set the current file as the active file.

When used on a Local template, the file is actually uploaded temporarily to the Livedocx servers, and deleted from their servers after generating the document.

If an error occurs while uploading the file, a Templates\ActiveException will be thrown.

If the file provided does not exist or is not readable, a FileExistsException will be thrown.

setName($name, $path)

Exceptions: none

$name string
$path string optional

Define the name of the template file with its path.

upload()

Exceptions: FileExistsException, Templates\UploadException

Upload the template file to Livedocx server.

If an error occurs while uploading the file, a Templates\UploadException will be thrown.

If the file provided does not exist or is not readable, a FileExistsException will be thrown.

Remote Templates

Usage

Remote templates are used to manipulate template files stored on Livedocx servers.

You can download them, delete them, check if the template you ask for exists (so you can upload it if it's not the case) or get a list of all fields that exist in the active template.

$remote = $livedocx->createRemoteTemplate();


$remote->setName('MyTemplate.docx');


if($remote->exists()) // this line is not necessary as setAsActive calls it behind the scene.
    $remote->setAsActive();


file_put_contents(__DIR__ . '/' . $remote->getName(), $remote->download());

Methods

delete()

Exceptions Templates\DeleteException

Delete a template from Livedocx servers. If the file does not exist, nothing happens.

If an error occurs while deleting the file, a Templates\DeleteException will be thrown.

download()

Exceptions Templates\DonwloadException, FileExistException

Get the contents of a template uploaded to Livedocx servers as a single string.

If the template does not exist on Livedocx, a FileExistsException will be thrown.

If an error occurs while downloading the file, a Templates\DonwloadException will be thrown.

exist()

Exceptions Templates\StatusException

Verify if the template file has been uploaded to Livedocx servers. Returns a boolean.

If an error occurs during the verification, a Templates\StatusException will be thrown.

getFieldNames()

Exceptions Templates\StatusException, Templates\NonActiveException

Get the list of all the available fields present on the template file. Returns an array.

If the template is not the active template, a Templates\NonActiveException will be thrown. If an error occurs while getting the fields list, a Templates\StatusException will be thrown.

getName()

Exceptions: none

Get the name of the template file as a string.

setAsActive()

Exceptions Templates\ActiveException, FileExistException

When used on a Remote template, the method first verify if the file has been uploaded on Livedocx servers, then set the file as active.

If the template does not exist on Livedocx, a FileExistsException will be thrown.

If an error occurs while setting the file as active, a Templates\ActiveException will be thrown.

setName($name)

Exceptions: none

$name string

Define the name of the template file.

Document

Usage

Documents are the files you generate when merging the fields with their value.

There are 2 ways of creating an instance of this class:

You can use the createDocument() method of the Livedocx class that will return an empty document
Or call the prepare() method of the Livedocx class that will also send the values you want to merge to the templates.

You can retrieve them either as document format: pdf doc docx rtf * ...

or as images: bitmaps files bmp jpg png tiff ... * Microsoft Office Metafiles

Images allow you to get only specific page range of the document (i.e. from page 2 to page 7).

You can define a password for the document, or restrict some actions with a set of permissions before creating it. These passwords and permissions are only available when retrieving the document as a pdf file.


$document  = $livedocx->prepare();


$document->setPassword('S3CR3T');
         ->create();


$images = $document->getAsBitmaps(1, 'jpg', 2, 7); // zoom, format, from page, to page
foreach($images as $pagenumber => $data)
{
    $filename = __DIR__ . '/' . 'image_'. $pagenumber . '.jpg';
    file_put_contents( $filename , $data);
}


file_put_contents(__DIR__ . '/' . 'myDocument.pdf', $document->retrieve('pdf'));

Methods

create()

Exceptions: Document\CreateException

Generate the document by merging the fields with their values

If an error occurs while generating the document, a Document\CreateException will be thrown.

getAccessOptions()

Exceptions: Document\PermissionsException

Get a list of defined permissions for the generated document.

If an error occurs while getting the list, a Document\PermissionsException will be thrown.

getAsBitmaps($zoomFactor, $format, $from, $to)

Exceptions: Document\BitmapsException, Document\InvalidException

$zoomFactor: int
$format: string
$from: int optional
$to: int optional

Retrieve the generated document as a set of Bitmaps. Return a array where the array key is the page number and the value is a binary string you can use directly or save on your server.

You can provide a start page and an end page if you want only some specific pages as bitmaps.

$images = $document->getAsBitmaps(1, 'jpg');
foreach($images as $pagenumber => $data)
{
    $filename = __DIR__ . '/' . 'image_'. $pagenumber . '.jpg';
    file_put_contents( $filename , $data);
}

If you don't provide correct parameters, a Document\InvalidException will be thrown.

If an error occurs while getting the bitmaps, a Document\BitmapsException will be thrown.

getAvailableFormats()

Exceptions: Document\StatusException

Return a list of all available document formats you can retrieve your document as. Return an array.

If an error occurs while getting the list, a Document\StatusException will be thrown.

getFormat()

Exceptions: none

Return the default format you set using setFormat() Return a string or null.

getMetaFiles($from, $to)

Exceptions: Document\InvalidException, Document\MetafilesException

$from: int optional
$to: int optional

Retrieve the generated document as a set of Microsoft Office Metafiles Return a array where the array key is the page number and the value is a binary string you can use directly or save on your server.

You can provide a start page and an end page if you want only some specific pages as metafiles.

$images = $document->getMetaFiles();
foreach($images as $pagenumber => $data)
{
    $filename = __DIR__ . '/' . 'metafile_'. $pagenumber . '.wmf';
    file_put_contents( $filename , $data);
}

If you don't provide valid parameters, a Document\InvalidException will be thrown.

If an error occurs while getting the metafiles, a Document\MetafilesException will be thrown.

retrive($format)

Exceptions: Document\InvalidException

$format: string optional

Retrieve the document as a binary string in the specified format.

If you don't provide a format, the default format set with setFormat() will be used.

If no format at all is provided, a Document\InvalidException will be thrown.

If an error occurs while retrieving the document, a Document\RetrieveException will be thrown.

setFormat($format)

Exceptions: none

$format: string

Define a default format to use when retrieving the document

setPassword($password)

Exceptions: Document\PasswordException

$password: string

Set a password required to open the generated document.

If an error occurs while setting the password, a Document\PasswordException will be thrown.

setPermissions($permissions, $password)

Exceptions: Document\PermissionsException, Document\InvalidException

$permissions: array
$password: string

Set a list of restricted permissions and a master password to unlock them.

If you don't provide valid parameters, a Document\InvalidException will be thrown.

If an error occurs while setting the password and permissions, a Document\PermissionsException will be thrown.

Image

Usage

Allow you to manage images to be included in your documents.

You can upload files to Livedocx, download them, delete them, get a list of all images already uploaded or check the image formats supported by Livedocx.

$image = $livedocx->createImage();
$image->setFilename('myImage.jpg', __DIR__ );


$image->upload();


$list = $image->listAll();
foreach($list as $image)
{
    var_dump($image['filename']);
}

Methods

delete()

Exceptions Image\DeleteException

Delete the image file from Livedocx servers

If an error occurs while deleting the file, a Image\DeleteException will be thrown.

download()

Exceptions: Image\DownloadException

Download the image from Livedocx server. Return a string

If an error occurs while downloading the file, a Image\DownloadException will be thrown.

exists()

Exceptions: Image\StatusException

Verify the existence of a file on Livedocx server. Return a boolean

If an error occurs while verifying the file, a Image\StatusException will be thrown.

getAcceptedFormats()

Exceptions: Image\StatusException

Get the list of all accepted image formats for upload Return an array

If an error occurs while obtaining the list, a Image\StatusException will be thrown.

getAvailableReturnFormats()

Exceptions: Image\StatusException

Get the list of all available image formats for document generation Return an array

If an error occurs while obtaining the list, a Image\StatusException will be thrown.

getName($full)

Exceptions: none

$full: boolean optional

Get the name of the image file Return a string

If the $full parameter is set, the path is also returned.

listAll()

Exceptions: Image\StatusException

Get a list of all images already uploaded to Livedocx servers Return an array

If an error occurs while obtaining the list, a Image\StatusException will be thrown.

setFilename($filename, $path)

Exceptions: none

$filename: string
$path: string optional

Define the name of the image file.

upload()

Exceptions: FileExistException, Image\UploadException

Upload the image to Livedocx servers

If the file provided does not exist, a FileExistException will be thrown.

If an error occurs while uploading the file, a Image\UploadException will be thrown.

Blocks

Usage

Block are sets of values in a repeated structure.

You define them by providing a set of fieldname => value bindings.

$block = $livedocx->createBlock();


$block->setName('attendees');


$block->bind(['firstname' => 'John', 'lastname' => 'Doe']);


$livedocx->assign($block);

Methods

bind($values)

Exceptions: Block\InvalidException

$values: array

Add one or multiple lines of values to a block This method is chainable.

When binding a set of values to a block, you can either do it line by line, or multiple lines at the same time.

$block->bind(['firstname' => 'Arnold', 'lastname' => 'Schwarzenegger'])
      ->bind(['firstname' => 'Chuck', 'lastname' => 'Norris'])
      ->bind(['firstname' => 'Jean-Claude', 'lastname' => 'Van Damme']);


// has exactly the same result as


$block->bind([
    ['firstname' => 'Arnold', 'lastname' => 'Schwarzenegger'],
    ['firstname' => 'Chuck', 'lastname' => 'Norris'],
    ['firstname' => 'Jean-Claude', 'lastname' => 'Van Damme']
]);

When you try to bind a value that is not contained in an array, a Block\InvalidException will be thrown.

getAllBlockNames()

Exceptions: Block\StatusException

Return the name of all blocks contained in the active template file. Return an array.

If an error occurs while obtaining the list, or no template has been set as active, a Block\StatusException will be thrown.

getFieldNames()

Exceptions: Block\StatusException, Block\NameException

Return the name of all fields contained in the block. Return an array.

If an error occurs while obtaining the list, or no template has been set as active, a Block\StatusException will be thrown.

If you call this method before giving the block a valid name, a Block\NameException will be thrown.

getFieldNames()

Exceptions: Block\StatusException, Block\NameException

Return the name of all fields contained in the block. Return an array.

If an error occurs while obtaining the list, or no template has been set as active, a Block\StatusException will be thrown.

If you call this method before giving the block a valid name, a Block\NameException will be thrown. (see getName() method)

getName()

Exceptions: Block\NameException

Return the name of the block if it has been set.

If no name has been set for the block, a Block\NameException will be thrown.

setName($name)

Exceptions: Block\NameException

$name: string

Define the name of the block.

If the provided name is not a valid string, a Block\NameException will be thrown.

Soap Client

Usage

The SOAP Client is heavilly used behind the scene, and you only have to manipulate a few of its methods. Constructor and connect are the only methods you will have to deal with.

The constructor takes a ext-soap \SoapClient as parameter, as you can see in the example below.

<?php
use Awakenweb\Livedocx\Soap\Client;
use Awakenweb\Livedocx\Livedocx;
use Awakenweb\Livedocx\Container;


// for free accounts:
$wsdl = 'https://api.livedocx.com/2.1/mailmerge.asmx?wsdl';
// for premium:
$wsdl = "https://premium01.livedocx.com/REPLACE_THIS_BY_YOUR_USERNAME/mailmerge.asmx?WSDL"
// for fully licensed: only you may know


$soap = new Client(new \SoapClient($wsdl));
$soap->connect(USERNAME, PASSWORD);


if($soap->isConnected()) {
    $Livedocx = new Livedocx($soap, new Container());
} else {
    throw new \Exception('WTF (What a Terrible Failure)');
}


// your code goes here

Methods

connect($username, $password)

Exceptions: Soap\ConnectException

$username: string
$password: string

Authenticate the user to the Livedocx webservice. This method is absolutely mandatory, as no API call can be done if this method has not been called before.

If an error occurs when authenticating, a Soap\ConnectException will be thrown.

isConnected()

Exceptions: none

Verify if the connect(...) method has been called. Returns a boolean.

__call($name, $arguments)

Exceptions: Soap\ConnectException, SoapException

This method acts as a proxy for any API call method. Returns the result of the API call.

If an API call is made before the connect(...) method has been called, a Soap\ConnectException will be thrown.

If an error occurs while making the actual API call, a SoapException will be thrown.