Bulk processing

Introduction

Bulk Processing is available in Premium licenses. Its multiple and comprehensive features allow to generate many documents from a template with maximum performance.

Thus, it is possible to open a DOCX as a template and then cache it in memory. Then replace its variables and create from one to several documents with the replaced variables.

Thanks to its internal cache and to being compatible with in-memory documents, replacement and creation of multiple variables and documents is done quickly and efficiently.

Available methods

Bulk Processing comes with the following set of methods to replace the different placeholders:

getDocuments: return the generated documents
replaceImage: replaces image placeholders
replaceList: replaces list placeholders
replaceTable: replaces table placeholders
replaceText: replaces text placeholders
replaceWordFragment: replaces placeholders by WordFragments

These methods can be called on the template individually or else combined in order to obtain the desired result. The chosen template is cached in memory, and so, its original content is reused to generate as many documents as necessary.

Generate and save documents

Working with Bulk Processing is really simple. You just have to create a BulkProcessing object, specifying the chosen template, call the desired replacement methods and save the generated document(s).

After using the placeholder replacement methods, getDocuments returns an array with the final documents. Every position of the returned array is a DOCXStructure object that can be saved as a file or serialized.

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// load the template
$bulk = new BulkProcessing('template.docx');

// do the replacements
(...)

// get the documents
$documents = $bulk->getDocuments();

// save the documents
for ($i = 0; $i < count($documents); $i++) {
    $documents[$i]->saveDocx('output_' . ($i + 1));
}

Data structure

Use a multidimensional array as structure to create documents and define its values. The first level shows the documents to be created, the sublevels contain the new values.

E.g., the following structure generates three documents with specified values:

$variables =
array(
    // first DOCX
    array(
        'name' => 'John',
        'address' => 'Acme Street 1',
    ),
    // second DOCX
    array(
        'name' => 'Mary',
        'address' => 'Acme Street 2',
    ),
    // third DOCX
    array(
        'name' => 'Tom',
        'address' => 'Acme Street 3',
    ),
);

Examples

Create and save three documents by replacing text placeholders:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// load the template
$bulk = new BulkProcessing('template.docx');

// set documents and values
$variables =
array(
    // first DOCX
    array(
        'date' => date('Y/m/d'),
        'name' => 'John',
        'address' => 'Acme Street 1',
        'url' => 'https://www.phpdocx.com',
        'signature' => 'phpdocx',
        'footer' => 'phpdocx\nfooter',
    ),
    // second DOCX
    array(
        'date' => date('Y/m/d'),
        'name' => 'Mary',
        'address' => 'Acme Street 2',
        'url' => 'https://www.phpdocx.com',
        'signature' => 'phpdocx',
        'footer' => 'phpdocx\nfooter',
    ),
    // third DOCX
    array(
        'date' => date('Y/m/d'),
        'name' => 'Tom',
        'address' => 'Acme Street 3',
        'url' => 'https://www.phpdocx.com',
        'signature' => 'phpdocx',
        'footer' => 'phpdocx\nfooter',
    ),
);
$options = array(
    'parseLineBreaks' => true,
);

// do the replacements
$bulk->replaceText($variables, $options);

// get the documents
$documents = $bulk->getDocuments();

// save the documents
for ($i = 0; $i < count($documents); $i++) {
    $documents[$i]->saveDocx('output_' . ($i + 1));
}

Generate two documents by replacing image and table placeholders:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// load the template
$bulk = new BulkProcessing('template.docx');

// set documents and values for image placeholders
$variables =
array(
    // first DOCX
    array(
        'LOGO' => 'image1.png',
    ),
    // second DOCX
    array(
        'LOGO' => 'image2.png',
    ),
);

// do the replacements
$bulk->replaceImage($variables);

// set documents and values for table placeholders
$variables =
array(
    // first DOCX
    array(
        array(
            array(
                'TABLE_1_PROJECT' => 'Project A',
                'TABLE_1_DATE' => date('Y/m/d'),
                'TABLE_1_ID' => '1A45A',
            ),
            array(
                'TABLE_1_PROJECT' => 'Project B',
                'TABLE_1_DATE' => date('Y/m/d'),
                'TABLE_1_ID' => 'EA78A',
            ),
            array(
                'TABLE_1_PROJECT' => 'Project C',
                'TABLE_1_DATE' => date('Y/m/d'),
                'TABLE_1_ID' => 'YA99A',
           ),
        ),
        array(
            array(
                'TABLE_2_ID' => 'ID122',
                'TABLE_2_NAME' => 'Name A',
                'TABLE_2_PROJECT' => 'Project 2A',
            ),
            array(
                'TABLE_2_ID' => 'ID123',
                'TABLE_2_NAME' => 'Name B',
                'TABLE_2_PROJECT' => 'Project 2B',
            ),
        ),
    ),
    // second DOCX
    array(
        array(
            array(
                'TABLE_1_PROJECT' => 'Other Project A',
                'TABLE_1_DATE' => date('Y/m/d'),
                'TABLE_1_ID' => 'Lvl 1A45A',
            ),
            array(
                'TABLE_1_PROJECT' => 'Other Project B',
                'TABLE_1_DATE' => date('Y/m/d'),
                'TABLE_1_ID' => 'Lvl EA78A',
            ),
            array(
                'TABLE_1_PROJECT' => 'Other Project C',
                'TABLE_1_DATE' => date('Y/m/d'),
                'TABLE_1_ID' => 'Lvl YA99A',
           ),
        ),
        array(
            array(
                'TABLE_2_ID' => 'Lvl ID122',
                'TABLE_2_NAME' => 'Name A',
                'TABLE_2_PROJECT' => 'Other Project 2A',
            ),
            array(
                'TABLE_2_ID' => 'Lvl ID123',
                'TABLE_2_NAME' => 'Name B',
                'TABLE_2_PROJECT' => 'Other Project 2B',
            ),
        ),
    ),
);

// do the replacements
$bulk->replaceTable($variables, $options);

// get the documents
$documents = $bulk->getDocuments();

// save the documents
for ($i = 0; $i < count($documents); $i++) {
    $documents[$i]->saveDocx('output_' . ($i + 1));
}

Create three documents by replacing text placeholders on all documents and replacing placeholders for WordFragments only on the first two documents:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

// load the template
$bulk = new BulkProcessing('template.docx');

// set documents and values for text placeholders
$variables =
array(
    // first DOCX
    array(
        'name' => 'John',
        'address' => 'Acme Street 1',
    ),
    // second DOCX
    array(
        'name' => 'Mary',
        'address' => 'Acme Street 2',
    ),
    // third DOCX
    array(
        'name' => 'Tom',
        'address' => 'Acme Street 3',
    ),
);
$options = array(
    'parseLineBreaks' => true,
);

// do the replacements
$bulk->replaceText($variables, $options);

// set documents and values for WordFragments
$nameA = new WordFragment();
$nameA->addText('John', array('bold' => true, 'font' => 'Arial'));

$nameB = new WordFragment();
$nameB->addText('Mary', array('bold' => true, 'font' => 'Arial'));

$linkA = new WordFragment();
$linkA->addLink('link to phpdocx', array('url'=> 'http://www.phpdocx.com', 'color' => '0000FF', 'u' => 'single'));

$linkB = new WordFragment();
$linkB->addLink('link to javadocx', array('url'=> 'http://www.javadocx.com', 'color' => '0000FF', 'u' => 'single'));

$variables =
array(
    // first DOCX
    array('url' => $linkA, 'name' => $nameA),
    // second DOCX
    array('url' => $linkB, 'name' => $nameB),
);
$options = array(
    'type' => 'inline',
);

// do the replacements
$bulk->replaceWordFragment($variables, $options);

// get the documents
$documents = $bulk->getDocuments();

// save the documents
for ($i = 0; $i < count($documents); $i++) {
    $documents[$i]->saveDocx('output_' . ($i + 1));
}

Tips

Generated documents can be opened from phpdocx as base templates, either as saved files or as in-memory DOCX.
It is not mandatory for the methods to set the same number of documents to be created. Bulk Processing allows to define different number of documents per method, creating or omitting the corresponding ones if necessary.
The package includes numerous examples of use for each method.
Unlike the CreateDocxFromTemplate methods, Bulk Processing replaces the placeholders of the document, header and footer targets by default. It is possible to define specific targets with the options of each method.
The parseMode option can be enabled to get template placeholders and repair internal placeholders. The parse mode is slower than the default one, but it's more accurate when the template includes placeholder symbols as regular contents.