README

俄语说明

这是一个 PHP 电子表格扩展，允许您从 Excel 模板导出 Excel 文件。使用此扩展，您无需从头开始使用代码创建 Excel 文件、设置样式等。

演示截图

简单示例

以下是一个最简单的示例（使用较少的代码）。假设我们有一个包含以下模板变量的 Excel 文件

代码如下

use alhimik1986\PhpExcelTemplator\PhpExcelTemplator;
require_once('vendor/autoload.php'); // if you don't use framework

PhpExcelTemplator::saveToFile('./template.xlsx', './exported_file.xlsx', [
	'{current_date}' => date('d-m-Y'),
	'{department}' => 'Sales department',
]);

结果如下

使用此扩展，我们只需创建一个包含所需样式的模板文件，并在其中指定模板变量。在代码中，我们只需将参数传递给模板变量。

功能

• 我们可以在一个表格单元格中插入多个模板变量（如果数据类型是 "字符串"）
• 我们可以插入一个一维数组，在这种情况下，将在表中创建额外的行
• 我们可以插入一个二维数组，在这种情况下，将在表中创建相应的列和行
• 通过指定单元格中的值，您可以在插入数组时更改这些单元格的样式
• 我们可以将相同的模板应用于表的多个工作表

功能演示和用法示例在 "samples" 文件夹中提供。

限制

• 在单个工作表中使用一维或二维数组时可能出现的所谓的副作用。特别是当它位于不对称的位置时。在 "samples" 文件夹中也提供了副作用示例。

安装

$ composer require alhimik1986/php-excel-templator

模板变量命名规则

规则可以是任何形式，但我可以提供我的模板变量命名建议

• {var_name} - 用于字符串值
• [var_name] - 用于一维数组
• [[var_name]] - 用于二维数组

如何插入一维数组，以便在表中创建列而不是行？

为此，使用以下方式插入二维数组而不是一维数组

$param['[[var_name]]'] = [['text 1', 'text 2', 'text 3']];

使用设置器

在上面的示例中，使用了没有设置器的最少的代码。在此代码中，数据类型（例如：字符串、一维数组或二维数组）被自动识别，并选择必要的设置器。但如果我们想使用特定的设置器，则相同的代码将如下所示

use alhimik1986\PhpExcelTemplator\PhpExcelTemplator;
use alhimik1986\PhpExcelTemplator\params\ExcelParam;
use alhimik1986\PhpExcelTemplator\params\CallbackParam;
use alhimik1986\PhpExcelTemplator\setters\CellSetterStringValue;

require_once('vendor/autoload.php'); // if you don't use framework

$params = [
	'{current_date}' => new ExcelParam(CellSetterStringValue::class, date('d-m-Y')),
	'{department}' => new ExcelParam(CellSetterStringValue::class, 'Sales department'),
];
PhpExcelTemplator::saveToFile('./template.xlsx', './exported_file.xlsx', $params);

目前该扩展有 3 种类型的设置器

• CellSetterStringValue（用于字符串值）
• CellSetterArrayValue（用于一维数组）
• CellSetterArray2DValue（用于二维数组）

您问，为什么需要显式指定设置器？

• 首先，因为它很灵活：假设您想创建自己的设置器，使用自己的算法消除我上面提到的副作用。
• 其次，在每个设置器中，我们可以传递一个回调函数，在其中我们可以更改插入的单元格的样式。例如，您需要用粗体字突出显示本月的最佳销售人员。

使用各种设置器的代码示例在 "samples" 文件夹中列出。

如何在不使用设置器的情况下设置样式？

在大多数情况下，显式使用设置器并不太方便。我猜您想使用最少的代码。因此，我使其成为可能，可以在不使用设置器的情况下设置样式

use alhimik1986\PhpExcelTemplator\PhpExcelTemplator;
use alhimik1986\PhpExcelTemplator\params\CallbackParam;
require_once('vendor/autoload.php'); // if you don't use framework

$params = [
	'{current_date}' => date('d-m-Y'),
	'{department}' => 'Sales department',
	'[sales_amount]' => [
		'10230',
		'45100',
		'70500',
	],
];

$callbacks = [
	'[sales_amount]' => function(CallbackParam $param) {
		$amount = $param->param[$param->row_index];
		if ($amount > 50000) {
			$cell_coordinate = $param->coordinate;
			$param->sheet->getStyle($cell_coordinate)->getFont()->setBold(true);
		}
	},
];

PhpExcelTemplator::saveToFile('./template.xlsx', './exported_file.xlsx', $params, $callbacks);

针对特殊模板的特殊设置器（CellSetterArrayValueSpecial）

有一些特殊模板，需要插入整行，而不是插入向下移动的单元格。此外，还需要合并单元格，包括包含模板变量的单元格。

对于这些模板，已创建了一个特殊设置器：CellSetterArrayValueSpecial。使用它的代码示例在文件夹：samples/8_special_template中给出。

事件

以下是可能的事件以及它们为何可以应用的原因说明

$events = [
    PhpExcelTemplator::BEFORE_INSERT_PARAMS => function(Worksheet $sheet, array $templateVarsArr) {
        // fires before inserting values into template variables        
    },
    PhpExcelTemplator::AFTER_INSERT_PARAMS => function(Worksheet $sheet, array $templateVarsArr) {
        // fires after inserting values into template variables.
        // It is used if you want to insert values​into a spreadsheet after columns and rows have been created. 
        // For example, when inserting an array of images.
        // If you insert images using $callbacks, then the images can shift to the right due to the fact that on the next line the template variable can create additional columns.
        // See an example: samples/10_images        
    },
    PhpExcelTemplator::BEFORE_SAVE => function(Spreadsheet $spreadsheet, IWriter $writer) {
        // fires before saving to a file. It is used when you need to modify the $writer or $spreadsheet object before saving, for example, $writer->setPreCalculateFormulas(false);        
    },
];
$callbacks = [];
$templateFile = './template.xlsx';
$fileName = './exported_file.xlsx';
$params = [
	// ...
];

PhpExcelTemplator::saveToFile($templateFile, $fileName, $params, $callbacks, $events);