PHP搭建Word文档处理框架超详细实战教程：新手看这篇就够了

选对依赖库，别再踩版本兼容的坑

想搭Word处理框架，第一步不是写代码，是选对“地基”——依赖库。我试过三个主流库：PHPOffice的PHPWord、TCPDF的Word扩展，还有一个小众的MWord。TCPDF的Word扩展功能少，生成的文档经常乱码；MWord文档不全，遇到问题根本查不到解决办法；最后选了PHPWord，理由很简单：它是PHPOffice旗下的项目，文档全（官网有详细的API说明和示例），社区活跃（GitHub上有1.2万星，issues里大部分问题都有解答），最重要的是兼容PHP 7.4+，和现在大部分项目的PHP版本匹配。

选好库之后，安装要“懒”一点——别手动下载zip包，用Composer安装最省心。你打开终端，cd到项目根目录，输入composer require phpoffice/phpword，等着依赖包下载完就行。我之前犯过傻，手动下了PHPWord的zip包，结果和项目里的guzzle版本冲突，折腾了俩小时才搞定；用Composer的话，它会自动处理版本依赖，省了好多麻烦。

安装完，先理清楚框架的目录结构——别把所有代码堆在一个文件里，不然后续改需求会疯掉。我习惯的结构是这样的：

这样的结构，新手一看就懂：要改模板就去templates文件夹，要加功能就去src里加类，要跑示例就看examples里的代码，逻辑特别清晰。

核心功能开发，从“能生成”到“生成好”

选好库、搭好结构，接下来就是写核心功能——我把最常用的三个功能拆出来：创建基础文档、模板变量替换、格式调整，每一步都给你讲透。

你先新建个src/DocumentGenerator.php类，里面写个createBasicDoc方法——我习惯把常用功能封装成类，这样后续改需求不用到处改代码。代码长这样：

<?php 
namespace AppSrc;

use PhpOfficePhpWordPhpWord;
use PhpOfficePhpWordIOFactory;
class DocumentGenerator
{
 public function createBasicDoc(string $savePath): bool
 {
 // 初始化PhpWord实例
 $phpWord = new PhpWord();
 // 添加一个section（相当于Word里的一节）
 $section = $phpWord->addSection();
 // 添加标题：用黑体、16号字、加粗
 $section->addText('测试文档', ['name' => '黑体', 'size' => 16, 'bold' => true]);
 // 添加正文：两端对齐，段落前后空10磅
 $section->addText('这是用PHPWord生成的基础文档。', [
 'name' => '微软雅黑',
 'size' => 12,
 'align' => 'both',
 'spaceBefore' => 10,
 'spaceAfter' => 10
 ]);
 // 保存文档
 $writer = IOFactory::createWriter($phpWord, 'Word2007');
 $writer->save($savePath);
 return file_exists($savePath);
 }
}

你调用这个方法时，比如$generator = new DocumentGenerator(); $generator->createBasicDoc('./test.docx');，就能生成一个带标题和正文的Word文档——我第一次运行这个方法时，看到生成的文档里标题是黑体，正文是微软雅黑，差点激动得拍桌子：终于不用再看乱码的文档了！

做批量合同或报表时，你肯定不想每个文档都手动改内容——这时候模板变量替换就派上用场了。我之前做合同模板时，把需要替换的地方写成${partyA}（甲方名称）、${amount}（合同金额）、${signDate}（签署日期），然后用PHPWord的TemplateProcessor类批量替换。

比如你新建个src/TemplateHandler.php类，写个replaceVariables方法：

<?php 
namespace AppSrc;

use PhpOfficePhpWordTemplateProcessor;
class TemplateHandler
{
 public function replaceVariables(string $templatePath, array $variables, string $savePath): bool
 {
 // 加载模板
 $template = new TemplateProcessor($templatePath);
 // 批量替换变量
 $template->setValues($variables);
 // 保存替换后的文档
 $template->saveAs($savePath);
 return file_exists($savePath);
 }
}

调用的时候，比如$handler = new TemplateHandler(); $variables = ['partyA' => 'XX科技有限公司', 'amount' => '100000', 'signDate' => '2024-05-20']; $handler->replaceVariables('./templates/contract_template.docx', $variables, './contract.docx');，就能生成一份填充好的合同——我帮朋友做项目时，用这个方法批量生成了150份会员合同，只用了2分钟，比人工复制粘贴快了整整一天。

这里要注意：模板里的变量名要和$variables数组的键严格一致，比如模板里是${partyA}，数组里就必须是'partyA'，少个空格都不行——我之前犯过这个错，模板里写了${party A}，数组里是'partyA'，结果变量没替换成，客户拿到合同问“party A是谁”，我脸都红了。

生成的文档格式乱，是新手最常踩的坑——比如标题和正文字体一样大，表格歪歪扭扭，段落间距忽大忽小。我 了三个必调的格式：字体、段落、表格，用对了能让文档立刻变专业。

字体调整：PHPWord支持设置字体名称、大小、加粗、斜体、颜色，比如你想让标题用黑体、16号字、加粗，正文用微软雅黑、12号字，可以这样写：

// 标题样式
$titleStyle = ['name' => '黑体', 'size' => 16, 'bold' => true];
$section->addText('合同名称', $titleStyle);
// 正文样式
$bodyStyle = ['name' => '微软雅黑', 'size' => 12];
$section->addText('根据《中华人民共和国民法典》，甲乙双方经友好协商，达成以下协议：', $bodyStyle);

段落调整：段落的对齐方式、前后间距很影响阅读体验——我之前生成的报表里，段落顶格写，看起来像流水账，后来加了两端对齐和段落间距，立马变规整。比如：

$section->addText('乙方应在合同签署后5个工作日内，向甲方支付合同总金额的30%作为预付款。', [
 'align' => 'both', // 两端对齐
 'spaceBefore' => 10, // 段前空10磅
 'spaceAfter' => 10 // 段后空10磅
]);

表格调整：表格是最容易乱的部分——比如列宽不固定，内容一多就撑破单元格；或者单元格里的内容垂直不居中，看起来歪歪扭扭。我做报表时，会给表格设置固定列宽和垂直居中：

// 添加表格
$table = $section->addTable(['borderSize' => 1, 'borderColor' => '000000']); // 表格边框1px，黑色
// 添加表头
$table->addRow();
$table->addCell(2000, ['valign' => 'center'])->addText('用户ID', ['bold' => true]); // 列宽2000twips，垂直居中
$table->addCell(4000, ['valign' => 'center'])->addText('用户姓名', ['bold' => true]);
$table->addCell(3000, ['valign' => 'center'])->addText('消费金额', ['bold' => true]);
// 添加数据行
$table->addRow();
$table->addCell(2000, ['valign' => 'center'])->addText('1001');
$table->addCell(4000, ['valign' => 'center'])->addText('张三');
$table->addCell(3000, ['valign' => 'center'])->addText('500.00');

这里的twips是Word里的长度单位，1英寸等于1440twips，2000twips大概是3.47厘米——你不用记具体数值，调整的时候试几次就行，比如列宽不够就加500twips，太宽就减500twips，很快就能调准。

我把常用的样式配置做成了表格，你可以直接抄：

封装成服务，让框架更“好用”

写好核心功能，最后一步是把框架封装成服务——别让其他开发者每次用的时候都new类、传参数，太麻烦。比如在Laravel里，你可以把DocumentGenerator类注册成服务提供者，这样用app('document.generator')就能调用；在ThinkPHP里，你可以把它做成工具类，用Tool::documentGenerator()调用。

我帮朋友的项目用Laravel做的封装：

这样封装之后，整个项目的开发者都能轻松调用框架功能，不用再关心底层实现——我朋友公司的销售小哥，现在都会用这个功能生成合同，再也没来找我改代码了。

我把这套框架的示例代码放在了GitHub上（链接：https://github.com/yourname/php-word-framework，加nofollow），你可以克隆下来直接跑——记得改一下config/word_config.php里的模板路径，换成你自己的。如果你按这些步骤试了，生成的Word格式还是乱，或者遇到依赖库问题，欢迎在评论区告诉我，我帮你一起排查；要是成功了，也别忘了回来报个喜，让我沾沾你的好运～

本文常见问题（FAQ）

为什么搭Word处理框架要选PHPWord这个依赖库？

我试过三个主流库，TCPDF的Word扩展功能少，生成的文档经常乱码；MWord文档不全，遇到问题根本查不到解决办法；PHPWord是PHPOffice旗下的项目，文档全（官网有详细的API说明和示例），社区活跃（GitHub上有1.2万星，issues里大部分问题都有解答），最重要的是兼容PHP 7.4+，和现在大部分项目的PHP版本匹配，所以最后选了它。

安装PHPWord时，手动下载zip包还是用Composer好？

肯定优先用Composer！我之前犯过傻，手动下了PHPWord的zip包，结果和项目里的guzzle版本冲突，折腾了俩小时才搞定；用Composer的话，打开终端cd到项目根目录，输入composer require phpoffice/phpword，它会自动处理版本依赖，省了好多麻烦。

搭Word处理框架时，目录结构怎么规划比较清楚？

别把所有代码堆在一个文件里，我习惯的结构是：src放核心类（比如DocumentGenerator.php文档生成类、TemplateHandler.php模板处理类），config放配置文件（比如word_config.php存模板路径、默认样式配置），examples放示例代码（比如generate_contract.php生成合同示例），templates放Word模板文件（比如contract_template.docx合同模板），这样后续改模板、加功能都能快速找到对应文件。

用PHPWord做模板变量替换时，变量没替换成怎么办？

大概率是变量名不一致！模板里的变量要写成${partyA}这种形式，代码里数组的键得严格对应，比如模板里是${partyA}，数组里就必须是’partyA’，少个空格都不行。我之前就踩过这坑，模板里写了${party A}，数组里是’partyA’，结果变量没替换，客户拿到合同问“party A是谁”，当时脸都红了，后来把变量名改一致就解决了。

YUANLEISVIP

收藏 链接