Add methods setValuesFromArray and cloneRowFromArray to the TemplateProcessor-class and update samples and docs accordingly

Author: geraldb-nicat

docs/templates-processing.rst

@@ -15,11 +15,27 @@ Example:
     $templateProcessor->setValue('Name', 'Somebody someone');
     $templateProcessor->setValue('Street', 'Coming-Undone-Street 32');
 
+You can also use ``TemplateProcessor::setValuesFromArray`` method to perform replacements from an array of "variable => value"-pairs.
+
+Example:
+
+.. code-block:: php
+
+    $replacements = [
+        'Name' => 'Somebody someone',
+        'Street' => 'Coming-Undone-Street 32'
+    ];
+    $templateProcessor = new TemplateProcessor('Template.docx');
+    $templateProcessor->setValuesFromArray($replacements);
+
 It is not possible to directly add new OOXML elements to the template file being processed, but it is possible to transform main document part of the template using XSLT (see ``TemplateProcessor::applyXslStyleSheet``).
 
 See ``Sample_07_TemplateCloneRow.php`` for example on how to create
 multirow from a single row in a template by using ``TemplateProcessor::cloneRow``.
 
+See ``Sample_37_TemplateCloneRowFromArray.php`` for example on how to create
+multirow from a single row with a two-dimensional array as data-source in a template by using ``TemplateProcessor::cloneRowFromArray``.
+
 See ``Sample_23_TemplateBlock.php`` for example on how to clone a block
 of text using ``TemplateProcessor::cloneBlock`` and delete a block of text using
 ``TemplateProcessor::deleteBlock``.

samples/Sample_37_TemplateCloneRowFromArray.php

@@ -0,0 +1,91 @@
+<?php
+include_once 'Sample_Header.php';
+
+// Template processor instance creation
+echo date('H:i:s'), ' Creating new TemplateProcessor instance...', EOL;
+$templateProcessor = new \PhpOffice\PhpWord\TemplateProcessor('resources/Sample_07_TemplateCloneRow.docx');
+
+// Variables on different parts of document
+$replacements = [
+    'weekday' => htmlspecialchars(date('l')), // On section/content
+    'time' => htmlspecialchars(date('H:i')), // On footer
+    'serverName' => htmlspecialchars(realpath(__DIR__)), // On header
+];
+$templateProcessor->setValuesFromArray($replacements);
+
+// Simple table
+$rows = [
+    [
+        'rowNumber' => 1,
+        'rowValue' => 'Sun'
+    ],
+    [
+        'rowNumber' => 2,
+        'rowValue' => 'Mercury'
+    ],
+    [
+        'rowNumber' => 3,
+        'rowValue' => 'Venus'
+    ],
+    [
+        'rowNumber' => 4,
+        'rowValue' => 'Earth'
+    ],
+    [
+        'rowNumber' => 5,
+        'rowValue' => 'Mars'
+    ],
+    [
+        'rowNumber' => 6,
+        'rowValue' => 'Jupiter'
+    ],
+    [
+        'rowNumber' => 7,
+        'rowValue' => 'Saturn'
+    ],
+    [
+        'rowNumber' => 8,
+        'rowValue' => 'Uranus'
+    ],
+    [
+        'rowNumber' => 9,
+        'rowValue' => 'Neptun'
+    ],
+    [
+        'rowNumber' => 10,
+        'rowValue' => 'Pluto'
+    ]
+];
+$templateProcessor->cloneRowFromArray('rowValue', $rows);
+
+// Table with a spanned cell
+$rows = [
+    [
+        'userId' => 1,
+        'userFirstName' => 'James',
+        'userName' => 'Taylor',
+        'userPhone' => '+1 428 889 773'
+    ],
+    [
+        'userId' => 2,
+        'userFirstName' => 'Robert',
+        'userName' => 'Bell',
+        'userPhone' => '+1 428 889 774'
+    ],
+    [
+        'userId' => 3,
+        'userFirstName' => 'Michael',
+        'userName' => 'Ray',
+        'userPhone' => '+1 428 889 775'
+    ]
+];
+$templateProcessor->cloneRowFromArray('userId', $rows);
+
+
+echo date('H:i:s'), ' Saving the result document...', EOL;
+$templateProcessor->saveAs('results/Sample_07_TemplateCloneRow.docx');
+
+echo getEndingNotes(array('Word2007' => 'docx'));
+if (!CLI) {
+    include_once 'Sample_Footer.php';
+}

src/PhpWord/TemplateProcessor.php

@@ -155,6 +155,20 @@ public function setValue($macro, $replace, $limit = self::MAXIMUM_REPLACEMENTS_D
         }
     }
 
+    /**
+     * Set values from a one-dimensional array of "variable => value"-pairs.
+     *
+     * @param array $values
+     *
+     * @return void
+     */
+    public function setValuesFromArray($values)
+    {
+        foreach ($values as $macro => $replace) {
+            $this->setValue($macro, $replace);
+        }
+    }
+
     /**
      * Returns array of all variables in template.
      *
@@ -234,6 +248,26 @@ public function cloneRow($search, $numberOfClones)
         $this->tempDocumentMainPart = $result;
     }
 
+    /**
+     * Clone a table row and populates it's values from a two-dimensional array in a template document.
+     *
+     * @param string $search
+     * @param array $rows
+     *
+     * @return void
+     */
+    public function cloneRowFromArray($search, $rows)
+    {
+        $this->cloneRow($search, count($rows));
+
+        foreach ($rows as $rowKey => $rowData) {
+            $rowNumber = $rowKey+1;
+            foreach ($rowData as  $macro => $replace) {
+                $this->setValue($macro.'#'.$rowNumber,$replace);
+            }
+        }
+    }
+
     /**
      * Clone a block.
      *