Cookbook

phpdocx is a very flexible tool regarding documents. It counts with every method required to replace and delete placeholders and other contents.

In order to work with templates, it is advisable to follow some good practices to ensure its proper functionality and performance.

Adding placeholders to templates

Placeholders are defined by adding a symbol to its beginning and end. The default symbol is $, as in $VAR_1$, $name$ ...

Different symbols can be set with the setTemplateSymbol method: #VAR#, ${VAR}, #{VAR}, |VAR|, {VAR}, [VAR]...

It is recommended to follow some advices when including placeholders in a template:

• To choose words not used in other regular contents in the document. E.g., $VAR_NAME$ instead of $name$.
• Not to use protected XML characters as template symbols: &, <, >, ".
• Placeholder replacement parses uppercase and lowercase letters.
• Not to use the same symbol that encloses placeholders for other contents. In case of not being possible to choose a symbol that is not already present in the template, it is advisable to enable parseMode. This option is available in the CreateDocxFromTemplate class and explained later in this same page: parseMode option.

Replacing placeholders in different targets

By default, phpdocx template methods replace placeholders in the main document. To replace placeholders in other contents of the document such as headers, footers, comments, endnotes or footnotes, you must set them in the target option.

It is possible to iterate every existing target in order to do a multiple replacement with a simple loop: Snippet: replace placeholders in all targets.

Replacement types: inline and block

When doing replacements with the replaceVariableByWordFragment, replaceVariableByHtml and removeTemplateVariable methods, it is possible to choose among two types of replacements: inline and block.

Inline replacements change the variable, just including the inline elements of the new content. MS Word doesn't allow to insert one paragraph inside another.

Block replacements delete the block that contains the placeholder, then add the new contents, being either of the inline or block type.

Premium licenses include inline-block replacements as well.

Parse mode option

When creating a document, MS Word may divide words and phrases in different tags in the internal XML that constitute a document. phpdocx needs to repair the placeholders in order to perform the replacements with its available methods.

By default, phpdocx reads and repair variables, checking every XML in its entirety. Because of this, it is recommended to choose a template symbol not used in the document for other contents, especially when working with the getTemplateVariables method.

phpdocx 13.5 includes a new parseMode option in CreateDocxFromTemplate to get template placeholders and repair internal placeholders by parsing and analyzing the XML contents of the document instead of reading the whole XML at once. This parse mode is a little slower than the default one, but it's more accurate when the template includes placeholder symbols as regular contents.

The following sample details how to use the parseMode option:

Optimizing the templates

As explained in the previous section, phpdocx has to repair the placeholders in order to do the replacements with the available template methods. The performance of this automatic repairment is excellent. However, it is possible to improve it by generating preprocessed templates, that is, templates which placeholders are already repaired.

phpdocx includes several methods to generate preprocessed templates. All the information about this, with detailed examples, is available in the page Improve performance when working with templates.

Defining a non unique symbol for placeholders

The symbol chosen for setting placeholders may be a unique one of 1 byte character only ($, #, @...) or different (${ }, { }, [ ]...), as explained in the API page setTemplateSymbol.

In case of using a non unique symbol or one of more than 1 byte (strlen), it is necessary to customize the static variable CreateDocxFromTemplate::$regExprVariableSymbols.

E.g., to work with { } as symbols:

This example illustrates a basic customization, but it can get much more elaborate in the cases that require so. Take notice that protected characters must be escaped.

If the parseMode option is enabled, it is not needed to customize this static variable: