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

<?php

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

setValue

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!

<?php

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

setValues

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

<?php

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

setCheckbox

Given a template containing a checkbox control with the title or tag named:

${checkbox}

The following will check the checkbox:

<?php

$templateProcessor->setCheckbox('checkbox', true);

To add a checkbox and set its title or tag in a template

Go to Developer tab > Controls group
Select the Check Box Content Control
Right-click on your checkbox
Click on Properties
Set the title or the tag

These steps may change regarding the version of Microsoft Word used.

setMacroOpeningChars

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

<?php

$templateProcessor->setMacroOpeningChars('{#');

setMacroClosingChars

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

<?php

$templateProcessor->setMacroClosingChars('#}');

setMacroChars

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

<?php

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

setImageValue

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}

Where: - [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.

Example:

${CompanyLogo}
${UserLogo:50:50} ${Name} - ${City} - ${Street}

<?php

$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);
});

cloneBlock

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

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

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

<?php

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

<?php

$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

replaceBlock

Given a template containing

${block_name}
This block content will be replaced
${/block_name}

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

<?php

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

deleteBlock

Same as previous, but it deletes the block

<?php

$templateProcessor->deleteBlock('block_name');

cloneRow

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

+-----------+----------------+
| ${userId} | ${userName}    |
|           |----------------+
|           | ${userAddress} |
+-----------+----------------+

<?php

$templateProcessor->cloneRow('userId', 2);

Will result in

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

cloneRowAndSetValues

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} |
+-----------+----------------+

<?php

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

applyXslStyleSheet

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

<?php

$xslDomDocument = new \DOMDocument();
$xslDomDocument->load('/path/to/my/stylesheet.xsl');
$templateProcessor->applyXslStyleSheet($xslDomDocument);

setComplexValue

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

<?php

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

setComplexBlock

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

<?php

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

setChartValue

Replace a variable by a chart.

<?php

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

save

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

<?php

$filepath = $templateProcessor->save();

saveAs

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

<?php

$pathToSave = 'path/to/save/file.ext';
$templateProcessor->saveAs($pathToSave);