version 2

README.md

@@ -32,12 +32,13 @@ composer require avadim/fast-excel-templator
 
 Example of template
 
-![demo1-tpl.png](demo1-tpl.png)
+![demo1-tpl.png](demo2-tpl.jpg)
 
 From this template you can get a file like this
 
-![demo1-out.png](demo1-out.png)
+![demo1-out.png](demo2-out.jpg)
 
+**Step 1** - open template and set replacements
 ```php
 // Open template and set output file
 $excel = Excel::template($tpl, $out);
@@ -50,67 +51,90 @@ $fillData = [
     '{{CITY}}' => 'Peace City, TN',
 ];
 
-// Replaces entire cell values for the sheet
+// Set replacements of entire cell values for the sheet
 // If the value is '{{COMPANY}}', then this value will be replaced,
 // but if the value 'Company Name {{COMPANY}}', then this value will not be replaced 
 $sheet->fill($fillData);
 
-// Replaces any occurring substrings
+// Set replacements of any occurring substrings
 // If the value is '{{DATE}}' or 'Date: {{DATE}}', then substring '{{DATE}}' will be replaced,
 $replaceData = ['{{BULK_QTY}}' => 12, '{{DATE}}' => date('m/d/Y')];
 $sheet->replace($fillData);
 ```
+**Step 2** - transfer the top of the sheet and the table headers from the template to the output file
+```php
+// Transfer rows 1-6 from templates to output file
+$sheet->transferRowsUntil(6);
+```
+There are 6 rows read from template, the output file also contains 6 lines
 
-Also, you can use any row as a template
+![demo1-out.png](demo2-1.jpg)
 
+**Step 3** - insert inner table rows
 ```php
-// Get the specified row (number 6) as a template
-$rowTemplate = $sheet->getRowTemplate(6);
-// You can insert template row many times with new data
-$rowData = [
-    // Value for the column A
-    'A' => 'AA-8465-947563',
-    // Value for the column B
-    'B' => 'NEC Mate Type ML PC-MK29MLZD1FWG',
-    // And so on...
-    'C' => 816,
-    'D' => 683,
-];
-// Replace row 6 instead of a template row
-$sheet->replaceRow(6, $rowTemplate, $rowData);
+// Get the row number 7 as a template and go to the next row in the template
+$rowTemplate = $sheet->getRowTemplate(7);
+
+// Fill row template and insert it into the output
+foreach ($allData as $record) {
+    $rowData = [
+        // In the column A wil be written value from field 'number'
+        'A' => $record['number'],
+        // In the column B wil be written value from field 'description'
+        'B' => $record['description'],
+        // And so on...
+        'C' => $record['price1'],
+        'D' => $record['price2'],
+    ];
+    $sheet->insertRow($rowTemplate, $rowData);
+}
+```
+We filled in and inserted rows 7, 8 and 9
 
-// New data for the new row
-$rowData = [
-    // ...
-];
-// Add new row from the same template after the last insertion
-$sheet->insertRowAfterLast($rowTemplate, $rowData);
+![demo1-out.png](demo2-2.jpg)
+
+**Step 4** - Now transfer the remaining rows and save file
+
+```php
+// Method transferRows() without arguments transfers remaining rows from the template to the output file 
+$sheet->transferRows();
 
 // ...
 // Save new file
 $excel->save();
-
 ```
 
+
+![demo1-out.png](demo2-3.jpg)
+
 You can find code examples in */demo* folder
 
 ## List of functions
 ### Class Excel
 
-Excel::template($template, $output);
+Excel::template($template, $output): Excel -- Open template file
 
-* fill(array $replacement) - Replaces the entire cell value for all sheets
-* replace(array $replacement) - Replaces a substring in a cell for all sheets
-* save()
+* sheet(?string $name = null): ?Sheet -- Select the specified sheet
+* fill(array $replacement) -- Set replacements of the entire cell value for all sheets
+* replace(array $replacement) -- Set replacements of substrings in a cells for all sheets
+* save(?string $fileName = null, ?bool $overWrite = true): bool -- Save generated XLSX-file
+* download(string $name = null): void -- Download generated file to client (send to browser)
 
 ### Class Sheet
 
-* fill(array $replacement) - Replaces the entire cell value for the sheet
-* replace(array $replacement) - Replaces a substring in a cell for the sheet
-* getRowTemplate($rowNumber) - Gets template from the row
-* insertRow($rowNumber, $rowTemplate, ?array $cellData = [])
-* replaceRow($rowNumber, $rowTemplate, ?array $cellData = [])
-* insertRowAfterLast($rowTemplate, ?array $cellData = [])
+* fill(array $replacement) -- Set replacements of the entire cell value for the sheet
+* replace(array $replacement) -- Set replacements of substrings in a cell for the sheet
+* getRowTemplate(int $rowNumber, ?bool $savePointerPosition = false) -- Gets template from the row
+* getRowTemplates(int $rowNumberMin, int $rowNumberMax, ?bool $savePointerPosition = false) -- Gets row template
+* transferRows(?int $countRows = null, $callback = null) -- Transfers rows from template to output
+* transferRowsUntil(?int $maxRowNum = null, $callback = null) -- Transfers rows from template to output
+* insertRow($rowTemplates, ?array $cellData = [])
+* skipRows(?int $countRows = null)
+* skipRowsUntil(?int $maxRowNum = null)
+
+### Class RowTemplateCollection
+
+* cloneCell(string $colSource, $colTarget, ?bool $checkMerge = false): RowTemplateCollection
 
 ## Do you like FastExcelTemplator?
 

composer.json

@@ -29,7 +29,7 @@
         "ext-xmlreader": "*",
         "ext-dom": "*",
         "avadim/fast-excel-helper": "^1.1",
-        "avadim/fast-excel-writer": "^5.1",
+        "avadim/fast-excel-writer": "^5.2",
         "avadim/fast-excel-reader": "^2.15"
     },
     "require-dev": {

demo/demo1.php

@@ -4,7 +4,6 @@
 
 require_once __DIR__ . '/../vendor/autoload.php';
 require_once __DIR__ . '/../src/autoload.php';
-
 $tpl = __DIR__ . '/files/demo1-tpl.xlsx';
 $out = __DIR__ . '/files/demo1-out.xlsx';
 
@@ -41,14 +40,17 @@
     ],
 ];
 
-// Replace strings and substrings on the sheet
+// Replacement strings and substrings on the sheet
 $sheet
-    ->fillValues($fillData)
-    ->replaceValues($replaceData)
+    ->fill($fillData)
+    ->replace($replaceData)
 ;
 
-// Get the specified row (number 6) as a template
-$rowTemplate = $sheet->getRowTemplate(6);
+// Transfer rows 1-6 from templates to output file
+$sheet->transferRowsUntil(6);
+
+// Get the specified row (number 7) as a template and go to the next row in the template
+$rowTemplate = $sheet->getRowTemplate(7);
 $count = 0;
 foreach ($list as $record) {
     $rowData = [
@@ -60,16 +62,11 @@
         'C' => $record['price1'],
         'D' => $record['price2'],
     ];
-    if ($count++ === 0) {
-        // First we replace the row 6 (this is template row)
-        $sheet->replaceRow(6, $rowTemplate, $rowData);
-    }
-    else {
-        // Then we add new rows after last touched
-        $sheet->insertRowAfterLast($rowTemplate, $rowData);
-    }
+    $sheet->insertRow($rowTemplate, $rowData);
 }
 
+$sheet->transferRows();
+
 $excel->save();
 
 echo 'Output file: ' . $out . '<br>';

demo/demo2.php

@@ -41,9 +41,12 @@
     ],
 ];
 
+// Transfer rows 1-3 from templates to output file
+$sheet->transferRowsUntil(3);
+
 $head = $sheet->getRowTemplate(4);
 $head->cloneCell('D', 'E-I');
-$sheet->replaceRow(4, $head, ['D' => 'January', 'E' => 'February', 'F' => 'March', 'G' => 'April', 'H' => 'May', 'I' => 'June']);
+$sheet->insertRow($head, ['D' => 'January', 'E' => 'February', 'F' => 'March', 'G' => 'April', 'H' => 'May', 'I' => 'June']);
 
 $rowTemplate = $sheet->getRowTemplate(5);
 $rowTemplate->cloneCell('D', ['E', 'F', 'G-I']);
@@ -59,12 +62,7 @@
         'H' => $locData['May'],
         'I' => $locData['June'],
     ];
-    if ($cnt === 1) {
-        $sheet->replaceRow(5, $rowTemplate, $rowData);
-    }
-    else {
-        $sheet->insertRowAfterLast($rowTemplate, $rowData);
-    }
+    $sheet->insertRow($rowTemplate, $rowData);
 }
 
 $excel->save($out);

demo/demo3.php

@@ -0,0 +1,69 @@
+<?php
+
+use avadim\FastExcelTemplator\Excel;
+
+require_once __DIR__ . '/../vendor/autoload.php';
+require_once __DIR__ . '/../src/autoload.php';
+
+$tpl = __DIR__ . '/files/demo3-tpl.xlsx';
+$out = __DIR__ . '/files/demo3-out.xlsx';
+
+$time = microtime(true);
+
+// Open template and set output file
+$excel = Excel::template($tpl);
+$excel->dateFormatter(true);
+$sheet = $excel->sheet();
+
+$invoiceNo = time();
+$invoiceDate = date('Y-m-d');
+$data = [
+    '{{INVOICE_NO}}' => $invoiceNo,
+    '{{INVOICE_DATE}}' => $invoiceDate,
+
+    '{{COMPANY_NAME}}' => 'Tech Prod Corp.',
+    '{{STREET_ADDRESS}}' => '123 ABC Street',
+    '{{CITY_ADDRESS}}' => 'Peace City',
+    '{{PHONE_NUMBER}}' => '(555) 555-1234'		,
+    '{{EMAIL_ADDRESS}}' => 'sales@tech-prod-corp.com',
+
+    '{{DUE_IN_DAYS}}' => '5',
+
+    '{{SHIPPING_NAME}}' => 'Joe Done',
+    '{{SHIPPING_ADDRESS}}' => 'Chennai St, TN',
+    '{{SHIPPING_PHONE}}' => '(444) 444-1234',
+
+    '{{BILLING_ADDRESS}}' => 'Kanya Kumari, TN',
+    '{{BILLING_PHONE}}' => '(333) 333-1234',
+    '{{BILLING_EMAIL}}' => 'bill@tech-prod-corp.com',
+
+    '{{REMARKS}}' => 'Some remarks are here',
+];
+
+$excel
+    ->fill($data)
+    ->replace(['{{INVOICE_NO}}' => $invoiceNo, '{{DUE_IN_DAYS}}' => '5'])
+;
+
+$sheet->transferRowsUntil(17);
+$rows = $sheet->getRowTemplates(18, 21);
+
+$firstRowNum = $sheet->lastWrittenRowNum() + 1;
+for ($i = 1; $i <= 9; $i++) {
+    $sheet->insertRow($rows, ['B' => 'item name ' . $i, 'D' => random_int(2, 20), 'E' => rand(1000, 9000) / 100]);
+}
+$lastRowNum = $sheet->lastWrittenRowNum();
+
+$formula = '=SUM(F' . $firstRowNum . ':F' . $lastRowNum . ')';
+
+$sheet->transferRows(null, function ($targetRowNum, $rowTemplate) use ($formula) {
+    if ($rowTemplate->rowNumber() === 22) {
+        $rowTemplate->setValue('F', $formula);
+    }
+    return $rowTemplate;
+});
+
+$excel->save($out);
+
+echo 'Output file: ' . $out . '<br>';
+echo 'Elapsed time: ' . round(microtime(true) - $time, 3) . ' sec';

demo/index.php

@@ -1,3 +1,22 @@
+<?php
+$items = [
+    [
+        'href' => 'demo1.php',
+        'label' => 'demo1.php',
+        'img-tpl' => 'img/demo1-tpl.jpg', 'img-out' => 'img/demo1-out.jpg',
+    ],
+    [
+        'href' => 'demo2.php',
+        'label' => 'demo2.php',
+        'img-tpl' => 'img/demo2-tpl.jpg', 'img-out' => 'img/demo2-out.jpg',
+    ],
+    [
+        'href' => 'demo3.php',
+        'label' => 'demo3.php',
+        'img-tpl' => 'img/demo3-tpl.jpg', 'img-out' => 'img/demo3-out.jpg',
+    ],
+];
+?>
 <!DOCTYPE html>
 <html lang="en">
 <head>
@@ -10,28 +29,19 @@
 </head>
 <body>
 <table>
+    <?php foreach ($items as $n => $item): ?>
     <tr>
         <td colspan="2">
-            <h2>Demo 1</h2>
-            <a href="demo1.php" target="_blank">demo1.php</a>
+            <h2>Demo <?=$n+1 ?></h2>
+            <a href="<?=$item['href'];?>" target="_blank"><?=$item['label'];?></a>
         </td>
     </tr>
     <tr>
-        <td><img src="../demo1-tpl.png"></td>
+        <td><img src="<?=$item['img-tpl'];?>"></td>
         <td>&nbsp;</td>
-        <td><img src="../demo1-out.png"></td>
-    </tr>
-    <tr>
-        <td colspan="2">
-            <h2>Demo 2</h2>
-            <a href="demo2.php" target="_blank">demo2.php</a>
-        </td>
-    </tr>
-    <tr>
-        <td><img src="../demo2-tpl.png"></td>
-        <td>&nbsp;</td>
-        <td><img src="../demo2-out.png"></td>
+        <td><img src="<?=$item['img-out'];?>"></td>
     </tr>
+    <?php endforeach; ?>
 </table>
 </body>
 </html>