Cookbook

Good practices when working with templates

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}, [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 is case sensitive.
  • 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. Uncommon symbols such as '¤' can also be used if needed.
  • RTL documents and some languages may add placeholder symbols in a different order or even change symbols by other characters. In this case the best approach is using symbols that we are sure will remain in the XML as they are added in the document.
  • If multiple placeholder symbols are used in the same document to set the variables to be replaced, it's recommended to call the setPreprocessed method to set preprocessed as false:

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 repairs 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 ($, |, #, @...) or different (${ }, { }, [ ], $[ ], [[ ]]...), as explained on the API page setTemplateSymbol.

When setting new placeholder symbols that use non unique symbols or one of more than 1 byte with setTemplateSymbol, phpdocx uses a regular expression in the static variable CreateDocxFromTemplate::$regExprVariableSymbols to handle the new placeholder symbols. This static variable uses ${ } as default placeholder symbols.

Since the release phpdocx 14.5, a new CreateDocxFromTemplate::$regExprVariableSymbols value is generated automatically when setting custom template placeholder symbols. Previous versions of phpdocx require setting a custom value for this static variable manually.

phpdocx 14.5 and newer manages all placeholder symbols automatically, but if a user wants to customize how placeholder symbols are handled, a new value can be set manually to CreateDocxFromTemplate::$regExprVariableSymbols.

E.g., to work with '##' as placeholder symbols without any contents between '##':

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.

Note that setTemplateSymbol generates a new CreateDocxFromTemplate::$regExprVariableSymbols value automatically. To customize this static variable manually, CreateDocxFromTemplate::$regExprVariableSymbols must be set after calling setTemplateSymbol.

If the parseMode option is enabled, it is not needed to customize CreateDocxFromTemplate::$regExprVariableSymbols:

Related information