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$ ...

Custom symbols can be set using the setTemplateSymbol method: |VAR|, @VAR@, #VAR#, ${VAR}, #{VAR}, [VAR], [[VAR]]...

It is recommended to follow these guidelines when including placeholders in a template:

  • Choose words that are not used elsewhere in the document’s regular content. E.g., $VAR_NAME$ instead of $name$.
  • Do not use protected XML characters as template symbols: &, <, >, ".
  • Placeholder replacement is case-sensitive.
  • It is recommended to use ${ } to wrap placeholders when the same symbol is not used at both the beginning and the end.
  • Do not use the same symbol that encloses placeholders for other content. 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 on 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 is more accurate when the template includes placeholder symbols as regular content.

The following sample details how to use the parseMode option:

The parseMode option can also be enabled and disabled by using the setParseMode method if needed:

Since phpdocx 17.5, a new internal algorithm has been added to provide faster and more accurate parsing when using the parse mode.

The parse mode internally uses the static variable CreateDocxFromTemplate::$regExprVariableParse. This variable contains a regular expression that defines the conditions for extracting the variables, with '[^\s](.+)[^\s]' as the default. If needed, this variable can be customized to use a different regular expression.

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 defining 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 longer than 1 byte using setTemplateSymbol and the parse mode is not enabled, 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 in 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