基于PHP搭建一个Word文档处理框架

lichongyang

3 月前

好——下面给你一份可直接落地的方案：用 PHP 搭建一个可扩展、可测试、可部署的 Word 文档处理框架（支持生成、模板填充、解析、合并、转换为 PDF/图片、权限与防宏处理、异步任务与扩展接口）。我把设计、关键组件、代码示例（可复制）、部署与安全注意点都写清楚，按你能直接实现的顺序来。

如果你想让我把这些文件生成为项目骨架（composer.json、示例类、API 路由等），告诉我你想用的框架（原生 PHP / Laravel / Slim / Lumen），我可以直接输出文件内容。

目标功能（最小可用版本 MVP）

上传 Word（.docx、.doc、.docm）并存储
从模板生成 Word（占位符替换）
读取/提取 Word 文本与元数据
合并多个 Word 文档
转换 Word → PDF（或图片）
防宏检测与拒绝含宏的文件（.docm）
支持异步任务（大文件/转换在后台处理）
REST API：上传、创建、转换、下载、状态查询

技术栈与第三方工具（推荐）

PHP 版本：8.1+
必备库：
- phpoffice/phpword — 生成、模板填充、合并、读写 .docx。 (composer require phpoffice/phpword)
- symfony/http-foundation（或使用框架自带）处理文件上传。
- league/flysystem — 文件抽象层（本地 / S3）。
转换工具（必须在服务器安装）：
- LibreOffice / soffice (headless) — 推荐用于 doc/docx → PDF/PNG 转换。
- （可选）unoconv、pandoc（当需要更多格式支持时）。
队列 / 异步：
- RabbitMQ / Redis队列 + worker (supervisord) 或者框架内置队列（Laravel Queue）
安全：
- clamav 或其他杀毒扫描 (扫描上传文件、拦截恶意宏)
存储：
- 本地磁盘或 S3（建议生产用 S3）

架构设计（模块化）

API 层：HTTP 路由、验证、身份（JWT 或 Session）
Controller / Handler：把请求转换成服务调用
Service 层：DocumentService、TemplateService、ConversionService
Storage 层：Flysystem 驱动（local / s3）
Worker：队列消费者，用于耗时任务（转换、长文件解析）
DB：记录任务与文档元数据（MySQL）
Security：文件类型验证、宏检测、杀毒扫描
Logging：处理日志和错误（每天 rotation）

项目目录示例

doc-processor/
├─ src/
│  ├─ Controller/
│  │  ├─ UploadController.php
│  │  ├─ TemplateController.php
│  ├─ Service/
│  │  ├─ DocumentService.php
│  │  ├─ TemplateService.php
│  │  ├─ ConversionService.php
│  ├─ Worker/
│  │  └─ ConversionWorker.php
│  ├─ Storage/
│  │  └─ FilesystemFactory.php
│  └─ Utils/
│     └─ MacroScanner.php
├─ public/
│  └─ index.php
├─ tests/
├─ composer.json
└─ docker/
   └─ Dockerfile + docker-compose.yml

关键实现（代码示例——框架无关，composer 可直接运行）

先给 composer.json 主要依赖：

{
  "require": {
    "php": "^8.1",
    "phpoffice/phpword": "^1.1",
    "league/flysystem": "^2.0",
    "symfony/http-foundation": "^6.0",
    "monolog/monolog": "^2.0"
  }
}

1) 简单的 DocumentService（上传 + 存储 + 防宏检查）

&lt;?php
namespace App\Service;

use League\Flysystem\FilesystemOperator;
use Symfony\Component\HttpFoundation\File\UploadedFile;

class DocumentService {
    private FilesystemOperator $storage;
    private string $tmpDir;
    private MacroScanner $scanner;

    public function __construct(FilesystemOperator $storage, MacroScanner $scanner, string $tmpDir = '/tmp') {
        $this->storage = $storage;
        $this->scanner = $scanner;
        $this->tmpDir = $tmpDir;
    }

    public function saveUploadedFile(UploadedFile $file, string $ownerId): array {
        // 基础验证
        $ext = strtolower($file->getClientOriginalExtension());
        if (!in_array($ext, ['doc','docx','docm'])) {
            throw new \InvalidArgumentException('不支持的文件类型');
        }

        // 存到临时位置
        $tmpPath = $this->tmpDir . '/' . uniqid('upload_') . '.' . $ext;
        $file->move(dirname($tmpPath), basename($tmpPath));

        // 宏检测（如果 docm/含宏就拒绝或隔离）
        if ($this->scanner->hasMacros($tmpPath)) {
            unlink($tmpPath);
            throw new \RuntimeException('文件包含宏，被拒绝上传');
        }

        // 进一步可调用 ClamAV 扫描...

        // 以日期分桶存储
        $dest = "documents/{$ownerId}/" . date('Y/m/d') . '/' . basename($tmpPath);
        $stream = fopen($tmpPath, 'rb');
        $this->storage->writeStream($dest, $stream);
        if (is_resource($stream)) fclose($stream);
        unlink($tmpPath);

        // 返回元数据（可存 DB）
        return ['path' => $dest, 'ext' => $ext, 'uploaded_at' => time()];
    }
}

MacroScanner（简单版）

&lt;?php
namespace App\Utils;

class MacroScanner {
    // 用最简单的方式：检测 .docm 扩展或 docx 中是否含 vbaProject.bin
    public function hasMacros(string $filePath): bool {
        $ext = pathinfo($filePath, PATHINFO_EXTENSION);
        if ($ext === 'docm') return true;
        if ($ext === 'docx') {
            // docx 其实是 zip，检查是否含 vbaProject.bin
            $zip = new \ZipArchive();
            if ($zip->open($filePath) === true) {
                $idx = $zip->locateName('word/vbaProject.bin', \ZipArchive::FL_NOCASE);
                $zip->close();
                return $idx !== false;
            }
        }
        return false;
    }
}

2) 模板填充（PhpWord Template）

&lt;?php
use PhpOffice\PhpWord\TemplateProcessor;

class TemplateService {
    public function fillTemplate(string $templatePath, array $vars, string $outPath) {
        $tp = new TemplateProcessor($templatePath);

        foreach ($vars as $k => $v) {
            // 模板中用 ${name} 这样的占位
            $tp->setValue($k, $v);
        }
        $tp->saveAs($outPath);
    }
}

示例模板中占位符用 ${name}、${date}。

3) 读取 .docx 文本（简易）

PhpWord 的读取支持有限，但可以用 Reader:

&lt;?php
use PhpOffice\PhpWord\IOFactory;

function extractTextFromDocx(string $path): string {
    $phpWord = IOFactory::load($path, 'Word2007');
    $text = '';
    foreach ($phpWord->getSections() as $section) {
        $elements = $section->getElements();
        foreach ($elements as $el) {
            if (method_exists($el, 'getText')) $text .= $el->getText() . "\n";
        }
    }
    return $text;
}

注意：复杂排版、表格、页眉页脚可能需要额外处理或用 LibreOffice 提取文本更稳妥。

4) 合并多个 docx（PhpWord）

合并较复杂，但思路是把文档内容复制到主文档（保持样式可能需额外处理）。示例参考 PhpWord 的 addExternalFile() 或循环拷贝元素。

5) 转换 Word → PDF（用 LibreOffice headless）

部署服务器需要安装 LibreOffice。命令行示例：

soffice --headless --convert-to pdf --outdir /path/to/out /path/to/input.docx

PHP 调用：

exec("soffice --headless --convert-to pdf --outdir " . escapeshellarg($outDir) . " " . escapeshellarg($inPath), $output, $ret);
if ($ret !== 0) { throw new \RuntimeException("转换失败: " . implode("\n",$output)); }

如果要把 PDF 转图片可使用 pdftoppm 或 ImageMagick（注意安全与性能）。

安全注意（必须执行）

拒绝包含宏的文件 或隔离处理（.docm 必慎）
对上传文件做 malware scan（ClamAV）
不要反序列化用户提交数据（和 serialize 相关）
限制文件大小（如 50MB），超大文件必须走分片上传与后台处理
对外部命令使用 escapeshellarg、限制运行用户（不要以 root 执行 soffice）
使用 CDN/S3 做公开下载，签名 URL（短期有效）
日志隐私：不在日志写入文件内容（敏感内容）

性能与可扩展性建议

对耗时任务（转换、合并、解析大文件）使用队列 + worker，用户收到任务 id 后轮询或通过 Webhook 通知。
使用 supervisord 或 systemd 管理 worker。
将临时转换任务放在独立容器或专用转换服务（减少主 web 容器压力）。
CPU 密集型任务（soffice）建议用多实例或 autoscale。
使用 S3 + 数字签名 URL 承载大文件，减少 webserver IO。

REST API 设计（示例）

POST /api/upload — 上传 Word，返回 document_id
POST /api/template/fill — body: { template_id, vars } → 返回 job_id（后台生成）
POST /api/convert — { document_id, target: pdf } → 返回 job_id
GET /api/job/{job_id} — 查询状态与下载地址
GET /api/document/{id}/download — 下载最终文件（可签名）

部署建议（Docker + docker-compose）

Web container (php-fpm + nginx)
Worker container (php-cli running worker)
LibreOffice container（或在 worker container 装 soffice）
Redis / RabbitMQ container
S3 (minio for testing)
ClamAV container

单元测试与 CI

用 PHPUnit 测试 TemplateService、MacroScanner、DocumentService（文件处理可 mock Filesystem）
CI：执行静态检查（PHPStan / Psalm）、单元测试、容器化构建

常见问题与解决方案

转换失败 / soffice 报错：检查 LibreOffice 版本、字体、权限、环境变量（DISPLAY 无关 headless，但有时需要 xvfb）
模板占位符断行/表格不替换：TemplateProcessor 不会跨段落替换，确保占位在单个文本段中；对复杂占位推荐使用 Word Content Controls（但 PHPWord 不直接支持），或用 docx 替换库（直接 zip 解压替换 XML）。
样式丢失：合并文档时可能冲突，需统一样式或先转换为 PDF 再合并 PDF。
中文/字体问题：LibreOffice 转 PDF 需要服务器安装对应中文字体（SimSun / Noto Sans CJK）。

进阶功能（可选）

文档注释/修订合并（复杂，考虑把 Word 转为 HTML，再处理）
支持 DOC（老格式） — 用 LibreOffice 转换为 DOCX 再处理
OCR：扫描图片型文档 → 使用 Tesseract 提取文本
权限与审计日志：记录谁修改、谁下载

小结（按步骤落地）

建立基础项目结构、安装 phpoffice/phpword 与 flysystem
实现上传 + MacroScanner + ClamAV 扫描
实现模板填充（TemplateProcessor）与文档下载
集成 LibreOffice 命令行进行转换（先在本地或开发容器测试）
把转换/合并任务搬到队列 worker（防止超时）
加入文件存储（S3）、日志、监控与安全扫描
编写单元测试，部署到生产容器，做好字体/soffice 配置