Templates processing

You can create an OOXML document template with included search-patterns (macros) which can be replaced by any value you wish. Only single-line values can be replaced. By default Macros are defined like this: ${search-pattern} but you can define custom macros. To load a template file, create a new instance of the TemplateProcessor.

$templateProcessor = new TemplateProcessor('Template.docx');


Given a template containing

Hello ${firstname} ${lastname}!

The following will replace ${firstname} with John, and ${lastname} with Doe . The resulting document will now contain Hello John Doe!

$templateProcessor->setValue('firstname', 'John');
$templateProcessor->setValue('lastname', 'Doe');


You can also set multiple values by passing all of them in an array.

$templateProcessor->setValues(array('firstname' => 'John', 'lastname' => 'Doe'));


You can define a custom opening macro. The following will set {# as the opening search pattern.



You can define a custom closing macro. The following will set #} as the closing search pattern.



You can define a custom opening and closing macro at the same time . The following will set the search-pattern like this: {#search-pattern#} .

$templateProcessor->setMacroChars('{#', '#}');


The search-pattern model for images can be like:
  • ${search-image-pattern}
  • ${search-image-pattern:[width]:[height]:[ratio]}
  • ${search-image-pattern:[width]x[height]}
  • ${search-image-pattern:size=[width]x[height]}
  • ${search-image-pattern:width=[width]:height=[height]:ratio=false}
  • [width] and [height] can be just numbers or numbers with measure, which supported by Word (cm, mm, in, pt, pc, px, %, em, ex)
  • [ratio] uses only for false, - or f to turn off respect aspect ration of image. By default template image size uses as ‘container’ size.


${UserLogo:50:50} ${Name} - ${City} - ${Street}
$templateProcessor = new TemplateProcessor('Template.docx');
$templateProcessor->setValue('Name', 'John Doe');
$templateProcessor->setValue(array('City', 'Street'), array('Detroit', '12th Street'));

$templateProcessor->setImageValue('CompanyLogo', 'path/to/company/logo.png');
$templateProcessor->setImageValue('UserLogo', array('path' => 'path/to/logo.png', 'width' => 100, 'height' => 100, 'ratio' => false));
$templateProcessor->setImageValue('FeatureImage', function () {
    // Closure will only be executed if the replacement tag is found in the template

    return array('path' => SlowFeatureImageGenerator::make(), 'width' => 100, 'height' => 100, 'ratio' => false);


Given a template containing See Sample_23_TemplateBlock.php for an example.

Customer: ${customer_name}
Address: ${customer_address}

The following will duplicate everything between ${block_name} and ${/block_name} 3 times.

$templateProcessor->cloneBlock('block_name', 3, true, true);

The last parameter will rename any macro defined inside the block and add #1, #2, #3 … to the macro name. The result will be

Customer: ${customer_name#1}
Address: ${customer_address#1}

Customer: ${customer_name#2}
Address: ${customer_address#2}

Customer: ${customer_name#3}
Address: ${customer_address#3}

It is also possible to pass an array with the values to replace the marcros with. If an array with replacements is passed, the count argument is ignored, it is the size of the array that counts.

$replacements = array(
    array('customer_name' => 'Batman', 'customer_address' => 'Gotham City'),
    array('customer_name' => 'Superman', 'customer_address' => 'Metropolis'),
$templateProcessor->cloneBlock('block_name', 0, true, false, $replacements);

The result will then be

Customer: Batman
Address: Gotham City

Customer: Superman
Address: Metropolis


Given a template containing

This block content will be replaced

The following will replace everything between ${block_name} and ${/block_name} with the value passed.

$templateProcessor->replaceBlock('block_name', 'This is the replacement text.');


Same as previous, but it deletes the block



Clones a table row in a template document. See Sample_07_TemplateCloneRow.php for an example.

| ${userId} | ${userName}    |
|           |----------------+
|           | ${userAddress} |
$templateProcessor->cloneRow('userId', 2);

Will result in

| ${userId#1} | ${userName#1}    |
|             |------------------+
|             | ${userAddress#1} |
| ${userId#2} | ${userName#2}    |
|             |------------------+
|             | ${userAddress#2} |


Finds a row in a table row identified by $search param and clones it as many times as there are entries in $values.

| ${userId} | ${userName}    |
|           |----------------+
|           | ${userAddress} |
$values = [
    ['userId' => 1, 'userName' => 'Batman', 'userAddress' => 'Gotham City'],
    ['userId' => 2, 'userName' => 'Superman', 'userAddress' => 'Metropolis'],
$templateProcessor->cloneRowAndSetValues('userId', $values);

Will result in

| 1 | Batman      |
|   |-------------+
|   | Gotham City |
| 2 | Superman    |
|   |-------------+
|   | Metropolis  |


Applies the XSL stylesheet passed to header part, footer part and main part

$xslDomDocument = new \DOMDocument();


Replaces a ${macro} with the ComplexType passed. See Sample_40_TemplateSetComplexValue.php for examples.

$inline = new TextRun();
$inline->addText('by a red italic text', array('italic' => true, 'color' => 'red'));
$templateProcessor->setComplexValue('inline', $inline);


Replaces a ${macro} with the ComplexType passed. See Sample_40_TemplateSetComplexValue.php for examples.

$table = new Table(array('borderSize' => 12, 'borderColor' => 'green', 'width' => 6000, 'unit' => TblWidth::TWIP));
$table->addCell(150)->addText('Cell A1');
$table->addCell(150)->addText('Cell A2');
$table->addCell(150)->addText('Cell A3');
$table->addCell(150)->addText('Cell B1');
$table->addCell(150)->addText('Cell B2');
$table->addCell(150)->addText('Cell B3');
$templateProcessor->setComplexBlock('table', $table);


Replace a variable by a chart.

$categories = array('A', 'B', 'C', 'D', 'E');
$series1 = array(1, 3, 2, 5, 4);
$chart = new Chart('doughnut', $categories, $series1);
$templateProcessor->setChartValue('myChart', $chart);


Saves the loaded template within the current directory. Returns the file path.

$filepath = $templateProcessor->save();


Saves a copy of the loaded template in the indicated path.

$pathToSave = 'path/to/save/file.ext';