README

MatoDocs 是一个用于编辑和加工 .docx 和 .html 文件并可选转换为 .pdf 格式的 PHP 库。

安装和配置

先决条件

使用此包需要 PHP。具体的安装留给用户。
使用 Composer 下载包的最新版本及其依赖项。
使用 Convertio API 将文档转换为 PDF 格式。

通过在项目的根目录下使用控制台命令将此包包含到您的项目中

composer require matogen/processor dev-master

如果您遇到类似“zip 扩展和 unzip/7z 命令都缺失，跳过”的错误，请取消注释 php.ini 文件中的 `extension=zip` 行。

此外，如果您计划从 URL 路径或 html 语法中下载图片，您还可以安装 Puppeteer。

npm i puppeteer

导入包

在导入包的类之前，您需要包含由 composer 生成的 autoload.php 脚本的路径。

# General path to autoload script
include_once __DIR__ . '/vendor/autoload.php';

# .docx processor, derived class import
use \Matogen\Processor\DocxProcessor

# .HTML processor, derived class import 
use \Matogen\Processor\HTMLProcessor

通用用例

以下示例展示了使用此包时的常见用例。

DocxProcessor

在处理 docx 模板之前，您需要首先实例化一个新的 DocxProcessor 类，并传递您的 Convertio API 密钥字符串以及您要编辑的 docx 模板的路径。

$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

进行文本编辑

您可以在模板文件中使用宏来指示您想要进行文本编辑的位置。这些宏的形式为 `${macro}`。在处理模板文件时，这些宏将被替换为实际要插入的文本。

为此，您需要提供一个包含宏及其关联文本的数组，您想要用它们替换。请注意，在构造数组时，您只需要宏的名称，而不是在模板文件中定义宏时使用的 `${}` 包围的值。

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of text edits
// 'Macro' => 'Text to be added'
$arrTextEdits = array(
    'TextEdit1' => 'First text edit.',
    'TextEdit2' => 'Second text edit.',
    'TextEdit3' => 'Third text edit.'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile($arrTextEdits);

以下是一个包含

Testing text edits, very exciting!
${TextEdit1} 
${TextEdit2}
${TextEdit3}

上面的示例将执行以下编辑

Testing text edits, very exciting!
First text edit. 
Second text edit.
Third text edit.

最后，替换宏的文本将采用宏的初始属性。例如，一个带有 12 号字体的斜体宏将被替换为同样带有 12 号字体的斜体文本。

进行图片编辑

与文本编辑类似，您可以在模板文件中使用宏来指示您想要插入图片的位置。在处理模板文件时，这些宏将被替换为实际要插入的图片。

为此，您需要提供一个包含宏及其关联图片路径的数组，您想要用它们替换。请注意，在构造数组时，您只需要宏的名称，而不是在模板文件中定义宏时使用的 `${}` 包围的值。

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of image edits
// 'Macro' => 'Image path string'
$arrImageEdits = array(
    'ImageEdit1' => 'path/to/image1.png',
    'ImageEdit2' => 'path/to/image2.png'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], $arrImageEdits);

以下是一个包含

Testing image edits, very exciting!
${ImageEdit1} 
${ImageEdit2}

上述示例将在路径存在的情况下，用正确的图片替换宏。与文本编辑不同，在插入图片时使用的宏可以有多种形式

${macro}
${macro:[width]:[height]:[ratio]}
${macro:[width]x[height]}
${macro:size=[width]x[height]}
${macro:width=[width]:height=[height]:ratio=false}

其中

[width]和[height]可以是纯数字，也可以是带有度量单位的数字，Word支持以下单位（cm, mm, in, pt, pc, px, %, em, ex）
[ratio]仅用于false, -或f来关闭尊重图像的宽高比。默认情况下，模板图像大小使用“容器”大小。

此信息也可以在处理数组中指定。使用上述示例，image1.png的宽度、高度和比例可以指定如下。

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of image edits
// 'Macro' => 'Image path string'
$arrImageEdits = array(
    'ImageEdit1' => array('path'=>'path/to/image1.png', 'width'=>100, 'height'=>100, 'ratio'=>false),
    'ImageEdit2' => 'path/to/image2.png'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], $arrImageEdits);

制作表格编辑

与文本编辑一样，您可以在模板文件中使用宏来指示您希望进行文本编辑的位置。这些宏的形式为`${macro}`。然后，在处理模板文件时，将这些宏替换为要插入的实际表格。这些宏的名称只用于构建数组，而不用于在模板文件中定义宏时使用的封装`${}`值。

为此，您需要提供一个包含宏及其相关表结构和要替换它们的值的数组的数组。请注意，当构建数组时，您只需要宏的名称，而不需要封装的`${}`值。

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of table edits
$arrTableEdits = array(
    'TableEdit1' => array(
        array('Text_row1_column1', 'Text_row1_column2', 'Text_row1_column3'),
        array('Text_row2_column1', 'Text_row2_column2', 'Text_row2_column3'),
        array('Text_row3_column1', 'Text_row3_column2', 'Text_row3_column3')
    )
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], [], $arrTableEdits);

对于上述示例，`$arrTableEdits`包含一个宏数组。每个宏都与一个二维数组关联，其中每个值对应于单元格的值。单元格在表格中的位置等于其在二维数组中的索引。

将图像插入单元格的步骤与通常将图像插入模板文件的步骤相同。不同之处在于，不是将图像的宏添加到模板文件中，而是使用表数组将宏写入指定的单元格。以下示例显示了如何使用`$arrTableEdits`将图像宏插入到表格的2行2列单元格中。在宏插入后，使用`$arrImageEdits`指示图像路径，就像通常在制作图像编辑时那样。

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of table edits
$arrTableEdits = array(
    'TableEdit1' => array(
        array('Text_row1_column1', 'Text_row1_column2', 'Text_row1_column3'),
        array('Text_row2_column1', '${ImageEdit1:150:150:f}', 'Text_row2_column3'),
        array('Text_row3_column1', 'Text_row3_column2', 'Text_row3_column3')
    )
);

$arrImageEdits = array(
    'ImageEdit1' => 'path/to/image1.png'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], $arrImageEdits, $arrTableEdits);

可以通过传递另一个包含所有表格样式数据的数组来向表格添加额外的样式，如下所示

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

$arrTableOptions = ['borderSize' => 12, 'borderColor' => 'green', 'width' => 100 * 50]

// Array of table edits
$arrTableEdits = array(
    'TableEdit1' => array(
        array('Text_row1_column1', 'Text_row1_column2', 'Text_row1_column3'),
        array('Text_row2_column1', 'Text_row2_column2', 'Text_row2_column3'),
        array('Text_row3_column1', 'Text_row3_column2', 'Text_row3_column3')
    )
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], [], $arrTableEdits, $arrTableOptions);

默认情况下，表格具有以下样式

borderSize: 12,
borderColor: Black
width: 100 * 50
unit: percentage

请注意，表格宽度将始终以五十分之一百分比进行测量。如果您想向单元格添加额外的样式效果，可以通过用另一个数组替换单元格的值来实现，该数组表示要添加到单元格的值以及特定单元格的样式信息数组，如下所示

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

$arrTableOptions = ['borderSize' => 12, 'borderColor' => 'green', 'width' => 100 * 50]

// Array of table edits
$arrTableEdits = array(
    'TableEdit1' => array(
        array('Text_row1_column1', 'Text_row1_column2', 'Text_row1_column3'),
        array('Text_row2_column1', ['value'=>'Text_row2_column2', 'style'=>['bgColor'=>'9966CC']], 'Text_row2_column3'),
        array('Text_row3_column1', 'Text_row3_column2', 'Text_row3_column3')
    )
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], [], $arrTableEdits);

此示例显示单元格在2行2列包含值'Text_row2_column2'，但还将具有紫色背景。有关表格和单元格样式信息的更多信息，请点击这里。

保存处理后的文件

以下简单示例显示了如何将处理后的文件保存为docx或pdf文件。如果输出目录不存在，它将被创建。

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of text edits
$arrTextEdits = array(
    'TextEdit1' => 'First text edit.',
    'TextEdit2' => 'Second text edit.',
    'TextEdit3' => 'Third text edit.'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile($arrTextEdits);

// Save file as docx
$docProcessor->saveFile('path\to\chosen\directory', $updatedDocx, false);
// Save file as pdf
$docProcessor->saveFile('path\to\chosen\directory', $updatedDocx, true);

将docx文件转换为pdf

如下所示，docx文件也可以直接转换为pdf，而无需先进行处理。就像保存处理后的文件一样，不存在的输出目录将被创建。

// Convert docx file to pdf
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');
$docProcessor->convertToPDF('path\to\chosen\directory', 'path\to\docx\file', false);

由Matogen企业软件开发部发布于2024

matogen / processor

维护者

详细信息