DOCXPath

Introduction

DOCXPath is available in Advanced and Premium licenses. This feature facilitates the low level work with DOCX documents through easy but powerful methods that allow you to insert, delete, replace, clone, move, import and return almost any Word content.

This feature benefits from the flexibility that a set of options adds. This set allows to filter by content type, position, text, parents, attributes or dynamic queries.

For example, it is possible to add a new image after any paragraph that contains a certain text, to place several new elements before a specific graph, to delete one or more rows from a table or a whole paragraph, or to replace one graph with another. The possibilities of DOCXPath are almost endless.

DOCXPath is compatible with new documents and templates, and its working environment is limited to document, header and footer contents. In the current stable package, footnotes or endnotes are out of its scope.

Insert elements

insertWordFragment: this method inserts WordFragments after the element specified in the document.

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// it is possible to use DOCXPath with a new document or a template
$docx = new CreateDocxFromTemplate('template.docx');

// create a new WordFragment
$content = new WordFragment($docx, 'document');
$content->addText('text added');
$content->addImage(array('src' => 'image.png' , 'scaling' => 50));

// set the reference node to insert the WordFragment
$referenceNode = array(
    'type' => 'paragraph',
    'occurrence' => 2,
    'contains' => 'Lorem',
);

// insert the new WordFragment after the reference node
$docx->insertWordFragment($content, $referenceNode, 'after');

// create the new document
$docx->createDocx('example_insertWordFragment');

Remove elements

removeWordContent: this method deletes existing elements in the document.

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// it is possible to use DOCXPath with a new document or a template
$docx = new CreateDocxFromTemplate('template.docx');

$referenceNode = array(
    'type' => 'paragraph',
    'occurrence' => 1,
);

// remove the reference node
$docx->removeWordContent($referenceNode);

// create the new document
$docx->createDocx('example_removeWordContent');

Replace elements

replaceWordContent: this method replaces an existing element by a WordFragment.

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// it is possible to use DOCXPath with a new document or a template
$docx = new CreateDocxFromTemplate('template.docx');

$content = new WordFragment($docx, 'document');
$content->addText('text added');
$content->addImage(array('src' => 'image.png' , 'scaling' => 50));

$referenceNode = array(
    'type' => 'paragraph',
    'occurrence' => 3,
);

$docx->replaceWordContent($content, $referenceNode);

$docx->createDocx('example_replaceWordFragment');

Clone elements

cloneWordContent: this method clones existing elements in the document.

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// it is possible to use DOCXPath with a new document or a template
$docx = new CreateDocxFromTemplate('template.docx');

$referenceToBeCloned = array(
    'type' => 'image',
);

$referenceNodeTo = array(
    'type' => 'paragraph',
    'contains' => 'closing paragraph',
);

// clone the reference node
$docx->cloneWordContent($referenceToBeCloned, $referenceNodeTo);

// create the new document
$docx->createDocx('example_cloneWordContent');

Move elements

moveWordContent: this method moves existing elements in the document.

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// it is possible to use DOCXPath with a new document or a template
$docx = new CreateDocxFromTemplate('template.docx');

$referenceNodeFrom = array(
    'type' => 'image',
);

$referenceNodeTo = array(
    'type' => 'paragraph',
    'contains' => 'closing paragraph',
);

// move the reference node
$docx->moveWordContent($referenceNodeFrom, $referenceNodeTo);

// create the new document
$docx->createDocx('example_moveWordContent');

Import contents

importContents: this method imports contents from a DOCX. Available only in Premium licenses.

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// it is possible to use DOCXPath with a new document or a template
$docx = new CreateDocxFromTemplate('template.docx');

// import charts
$referenceNode = array(
    'type' => 'chart',
);

$docx->importContents('document.docx', $referenceNode);

// create the new document
$docx->createDocx('example_moveWordContent');

Get Word contents

getWordContents: this method returns the text values of existing elements.

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// it is possible to use DOCXPath with a new document or template
$docx = new CreateDocxFromTemplate('template.docx');

$referenceNode = array(
    'type' => 'paragraph',
    'contains' => 'heading',
);

// get the text contents from the reference node
$contents = $docx->getWordContents($referenceNode);

// print the text values
print_r($contents);

How to obtain information from a performed query

The previous commands act over the first result of a XPath query. If you need to obtain information about the data the Xpath query returns, you can run the getDocxPathQueryInfo method. Thanks to this new method it is possible to get the number of the concurrent results and the string of the query. For example, this allows to go across all concurrent elements with a loop to perform a certain action.

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// it is possible to use DOCXPath with a new document or template
$docx = new CreateDocxFromTemplate('template.docx');

$referenceNode = array(
    'type' => 'paragraph',
    'contains' => 'text',
);

$queryInfo = $docx->getDocxPathQueryInfo($referenceNode);

var_dump($queryInfo);

Tips

When inserting elements, you can use four placing types: before, after, inlineBefore and inlineAfter. The first two place the content as a block type (for example, a paragraph). The other two place contents as inline ones.
The following options indicate the references to the contents: type (string, element type, any as default), contains (string, text value), occurrence ((int) exact occurrence or (string) range of contents (e.g.: 2..9, 2.., ..9) or first() or last(), if empty iterate all elements), attributes (string, contains a specific attribute key and value), parent (string, main document body as default, allows to set any parent or a specific one), customQuery (custom XPath query, overwrites any other reference).
If the option occurrence is not set all references of the query will be changed.
When setting a referenceNode it is mandatory to employ at least one of the available options. You can combine them freely.
If the reference you indicate doesn't exist, the method doesn't add the WordFragment. It is possible to run the $forceAppend parameter to force the addition of the new content, even if the reference you indicate doesn't exist.
If you need to set the last occurrence of an element you can use the value -1. The first element is always 1, unlike PHP arrays, in which the first element is 0.