the first release

README.md

@@ -1,13 +1,16 @@
 # FastExcelTemplator
 
-This is a part of the **FastExcelPhp Project**
+**FastExcelTemplator** is a part of the **FastExcelPhp Project** which consists of
 
-This library **FastExcelTemplator** can generate Excel-compatible spreadsheets in XLSX format (Office 2007+) from XLSX templates, 
-very quickly and with minimal memory usage.
+* [FastExcelWriter](https://packagist.org/packages/avadim/fast-excel-writer) - to create Excel spreadsheets
+* [FastExcelReader](https://packagist.org/packages/avadim/fast-excel-reader) - to reader Excel spreadsheets
+* [FastExcelTemplator](https://packagist.org/packages/avadim/fast-excel-templator) - to generate Excel spreadsheets from XLSX templates
+* [FastExcelLaravel](https://packagist.org/packages/avadim/fast-excel-laravel) - special **Laravel** edition
 
 ## Introduction
 
-This library is designed to be lightweight, super-fast and requires minimal memory usage.
+**FastExcelTemplator** can generate Excel-compatible spreadsheets in XLSX format (Office 2007+) from XLSX templates,
+very quickly and with minimal memory usage. This library is designed to be lightweight, super-fast and requires minimal memory usage.
 
 **Features**
 
@@ -32,19 +35,80 @@ require 'path/to/fast-excel-templator/src/autoload.php';
 
 ## Usage
 
-You can find more examples in */demo* folder
+Example of template
 
+![img1-tpl.png](img1-tpl.png)
 
+From this template you can get a file like this
 
-## Excel
+![img1-out.png](img1-out.png)
+
+```php
+// Open template and set output file
+$excel = Excel::template($tpl, $out);
+// Get the first sheet
+$sheet = $excel->sheet();
+
+$fillData = [
+    '{{COMPANY}}' => 'Comp Stock Shop',
+    '{{ADDRESS}}' => '123 ABC Street',
+    '{{CITY}}' => 'Peace City, TN',
+];
+
+// Replaces 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
+// 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);
+```
+
+Also, you can use any row as a template
+
+```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);
+
+// New data for the new row
+$rowData = [
+    // ...
+];
+// Add new row from the same template after the last insertion
+$sheet->insertRowAfterLast($rowTemplate, $rowData);
+
+// ...
+// Save new file
+$excel->save();
+
+```
+
+You can find code examples in */demo* folder
+
+## List of functions
+### Class Excel
 
 Excel::template($template, $output);
 
 * 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
+### 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

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "avadim/fast-excel-templator",
-    "description": "Lightweight and very fast XLSX Excel Spreadsheet Writer in PHP",
+    "description": "Lightweight and very fast Excel Spreadsheet generator from XLSX-templates in PHP",
     "keywords": [
         "php",
         "excel",

demo/index.php

@@ -0,0 +1,76 @@
+<?php
+
+use avadim\FastExcelTemplator\Excel;
+
+require_once __DIR__ . '/../vendor/autoload.php';
+require_once __DIR__ . '/../src/autoload.php';
+
+$tpl = __DIR__ . '/files/demo-tpl.xlsx';
+$out = __DIR__ . '/files/demo-out.xlsx';
+
+$time = microtime(true);
+
+// Open template and set output file
+$excel = Excel::template($tpl, $out);
+$sheet = $excel->sheet();
+
+$fillData = [
+    '{{COMPANY}}' => 'Comp Stock Shop',
+    '{{ADDRESS}}' => '123 ABC Street',
+    '{{CITY}}' => 'Peace City, TN',
+];
+$replaceData = ['{{BULK_QTY}}' => 12, '{{DATE}}' => date('m/d/Y')];
+$list = [
+    [
+        'number' => 'AA-8465-947563',
+        'description' => 'NEC Mate Type ML PC-MK29MLZD1FWG (Corei5-3470S/2GB/250GB/Multi/No OF/Win 11 Home)',
+        'price1' => 816,
+        'price2' => 683,
+    ],
+    [
+        'number' => 'QR-7956-048914',
+        'description' => 'Acer Aspire TC-1760-UA92 (Core i5-12400/12GB 3200MHz DDR4/512GB SSD/Win 11 Home)',
+        'price1' => 414,
+        'price2' => 339,
+    ],
+    [
+        'number' => 'BD-3966-285936',
+        'description' => 'Dell Optiplex 7050 SFF (Core i7-7700/32GB DDR4/1TB SSD/Win 10 Pro/Renewed)',
+        'price1' => 249,
+        'price2' => 198,
+    ],
+];
+
+// Replace strings and substrings on the sheet
+$sheet
+    ->fill($fillData)
+    ->replace($replaceData)
+;
+
+// Get the specified row (number 6) as a template
+$rowTemplate = $sheet->getRowTemplate(6);
+$count = 0;
+foreach ($list 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'],
+    ];
+    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);
+    }
+}
+
+$excel->save();
+
+echo 'Output file: ' . $out . '<br>';
+echo 'Elapsed time: ' . round(microtime(true) - $time, 3) . ' sec';