Cookbook

INTRODUCTION

PRACTICAL PHPDOCX

CONVERSION PLUGIN

COOKBOOK

SNIPPETS

API DOCUMENTATION

HTMLAPI DOCUMENTATION

XMLAPI DOCUMENTATION

CASE STUDIES

Improve performance when working with templates

phpdocx is a fast library, but working with templates with multiple variables may require users to run specific options and methods to achieve the best performance.

We're going to see the available features to optimize the process when working with templates.

Let's apply this optimization in a practical way. We'll set a hundred iterations with 360 variables in a template. That sums 36,000 replacements. For each item we detail the script and the execution time.

Replacement of the variable without optimizations

The usual steps to replace placeholders in templates are uploading the document with the CreateDocxFromTemplate class, then, running the method replaceVariableByText to replace those placeholders for its new values:

<?php

require_once 'classes/CreateDocx.php';

// iterate a hundred times
for ($i = 0; $i < 100; $i++) { 
    // set the template 
    $docx = new CreateDocxFromTemplate('template_not_optimized.docx');
    //  get the complete set of placeholders. You can indicate individually each placeholder.
    $documentVariables = $docx->getTemplateVariables();

    // as a demostration of the script way of working, assign a value to each placeholder
    $arrayValues = array();
    $j = 0;
    foreach ($documentVariables['document'] as $documentVariable) {
        $arrayValues[$documentVariable] = 'new value ' . $j++;
    }

    // replace the placeholders 
    $docx->replaceVariableByText($arrayValues);

    // create a document for each iteration
    $docx->createDocx('output/output_' . $i . '.docx');   
}

The execution time of the script is as follows:

real	0m25.006s
user	0m24.940s
sys	0m0.052s

Replacement of variables with preprocessed documents

When writing texts, Word tends to add extra tags that are not relevant to the document, mainly related to erasing and correcting texts and to words not found in the dictionary.

For example, the text tag:

<w:r><w:tab/><w:t>$VAR_60_4$</w:t></w:r>

...can turn to:

<w:r><w:tab/><w:t>$</w:t></w:r><w:r w:rsidR="000E5193"><w:t>VAR_6</w:t></w:r><w:r><w:t>0_4$</w:t></w:r>

In order to replace those placeholders properly, phpdocx cleans the XML, which takes some execution time.

The constructor of the CreateDocxFromTemplate class allows easily to indicate to phpdocx that the document is preprocessed:

$docx = new CreateDocxFromTemplate('template_not_optimized.docx', array('preprocessed' => true));

To make this code work, the document must be preprocessed. That means that the placeholders musn't include “trash tags”.

You can achieve this preprocess in three ways:

Extracting the DOCX from the template with a tool like WinZIP or WinRAR and manually correcting it. Then, compressing it in a ZIP again and setting the document with a DOCX extension.
Using the processTemplate method, available in all licenses.
Using the standalone ProcessTemplate class, available in the Premium license.

To run ProcessTemplate and generate a preprocessed template, execute the following code:

require_once 'classes/CreateDocx.php';

$docx = new ProcessTemplate();
$docx->optimizeTemplate('template_not_optimized.docx', 'template_optimized.docx', $variables);

$variables is an array with the variables you're going to optimize. With the method $docx->getTemplateVariables(); you can obtain automatically the complete variable list.

When the document is already processed, you can replace the placeholder with this script:

<?php

require_once 'classes/CreateDocx.php';

// iterate a hundred times
for ($i = 0; $i < 100; $i++) { 
    // set the template, indicating that the document is preprocessed
    $docx = new CreateDocxFromTemplate('template_optimized.docx', array('preprocessed' => true));
    // get the complete set of placeholders. You can indicate individually each placeholder.

    $documentVariables = $docx->getTemplateVariables();

    // as a demostration of the script way of working, assign a value to each placeholder
    $arrayValues = array();
    $j = 0;
    foreach ($documentVariables['document'] as $documentVariable) {
        $arrayValues[$documentVariable] = 'new value ' . $j++;
    }

    // replace the placeholders 
    $docx->replaceVariableByText($arrayValues);

    // create a document for each iteration 
    $docx->createDocx('output/output_' . $i . '.docx');   
}

The execution time of the script is as follows:

real	0m14.733s
user	0m14.612s
sys	0m0.056s

In regard to the original script, this process reduces the time in about 10.5 seconds.

Replacement of raw type variables

If the values for the placeholder replacement are not WordFragments but plain text, you can improve the performance with the "raw" option available in the replaceVariableByText method.

When the document is already processed, execute the following script:

<?php

require_once 'classes/CreateDocx.php';

// iterate a hundred times
for ($i = 0; $i < 100; $i++) { 
    // upload the template, indicating that the process is preprocessed 
    $docx = new CreateDocxFromTemplate('template_optimized.docx', array('preprocessed' => true));
    // get the complete set of placeholders. You can indicate individually each placeholder.
    $documentVariables = $docx->getTemplateVariables();

    // as a demostration of the script way of working, assign a value to each placeholder
    $arrayValues = array();
    $j = 0;
    foreach ($documentVariables['document'] as $documentVariable) {
        $arrayValues[$documentVariable] = 'new value ' . $j++;
    }

    // replace the placeholder by setting up the raw option
    $docx->replaceVariableByText($arrayValues, array('raw' => true);

    // create a document for each iteration
    $docx->createDocx('output/output_' . $i . '.docx');   
}

The execution time of the script is as follows:

real	0m1.744s
user	0m1.700s
sys	0m0.028s

In regard to the original script, this process reduces the time in about 23 seconds.