解决 PHPWord 中 UTF-8 字符导致的 XML 格式异常问题-php教程-PHP中文网

解决 PHPWord 中 UTF-8 字符导致的 XML 格式异常问题

本文详解如何修复因 draftjs json 数据经 php 处理后产生非法 utf-8 编码，进而引发 phpword 生成 word 文档时 xml 结构损坏的问题。核心在于统一字符编码处理、避免重复转义与 dom 解析失败。

本文详解如何修复因 draftjs json 数据经 php 处理后产生非法 utf-8 编码，进而引发 phpword 生成 word 文档时 xml 结构损坏的问题。核心在于统一字符编码处理、避免重复转义与 dom 解析失败。

在使用 DraftJS + PHPWord 构建动态 Word 文档（尤其是模板合并场景）时，一个典型且隐蔽的问题是：生成的 document.xml 出现格式异常（如标签闭合错乱、属性缺失、DOM 解析失败），最终导致 Word 文件无法打开或内容丢失。根据问题描述与调试结论，根本原因并非逻辑错误，而是 UTF-8 字符在多层处理中被重复编码或未正确转义，破坏了 OpenXML 规范所需的严格 XML 结构。

? 问题根源分析

DraftJS 输出为 UTF-8 JSON：$result['snapshot'] 是标准 UTF-8 编码的 JSON 字符串；
json_decode() 后未校验编码完整性：若原始 JSON 含 BOM 或混合编码（如部分字段被前端错误编码为 ISO-8859-1），json_decode($str, true) 可能返回 null 或截断字符串，但代码中缺乏检查；
xmlEntities() 使用不当：函数内部若直接调用 htmlspecialchars($str, ENT_XML1, 'UTF-8') 是安全的，但若误用 htmlentities() 或遗漏 'UTF-8' 参数，在非 ASCII 字符（如中文、重音字母）上会生成无效实体或乱码；
DOMDocument 加载前未标准化编码：$sourceDom->loadXML($sourceDocument) 要求输入必须是格式良好的 UTF-8 XML。若 $sourceDocument 因前述问题含非法字节序列（如 \x00-\x08, \x0B\x0C, \x0E-\x1F），loadXML() 将静默失败或产生畸形 DOM。

✅ 正确解决方案

1. 强制标准化输入编码

在 json_decode 后立即清理并验证 UTF-8：

$snapshot = $result['snapshot'];
// 移除可能的 BOM 并确保纯 UTF-8
$snapshot = mb_convert_encoding($snapshot, 'UTF-8', 'UTF-8');
$snapshot = preg_replace('/^\xEF\xBB\xBF/', '', $snapshot); // 移除 UTF-8 BOM
$decoded = json_decode($snapshot, true);
if ($decoded === null) {
    throw new InvalidArgumentException('Invalid UTF-8 JSON in snapshot: ' . json_last_error_msg());
}

2. 安全的 XML 实体转义函数

替换原有 xmlEntities() 为鲁棒实现：

function xmlEntities(string $input): string {
    // 移除控制字符（XML 1.0 不允许）
    $input = preg_replace('/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/u', '', $input);
    // 转义关键字符，强制 UTF-8
    return htmlspecialchars($input, ENT_XML1 | ENT_QUOTES, 'UTF-8');
}

⚠️ 注意：ENT_XML1 确保仅转义 & "（符合 XML 规范），避免 htmlspecialchars() 默认转义单引号（'）导致 Word 解析异常。

PHP 8.5.5
PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

3. DOM 加载前预检与修复

在 $sourceDom->loadXML() 前添加验证：

// 验证 XML 是否为良构 UTF-8
if (!mb_check_encoding($sourceDocument, 'UTF-8')) {
    throw new RuntimeException('Source document is not valid UTF-8');
}
// 移除 XML 声明外的空白（防止 DOM 加载失败）
$sourceDocument = trim($sourceDocument);
if (substr($sourceDocument, 0, 5) === '<?xml ') {
    $sourceDocument = preg_replace('/^<\?xml[^>]*\?>\s*/', '', $sourceDocument);
}

$sourceDom = new DOMDocument();
$sourceDom->preserveWhiteSpace = false;
$sourceDom->formatOutput = false;
// 关闭 libxml 错误报告，避免警告干扰
libxml_use_internal_errors(true);
if (!$sourceDom->loadXML($sourceDocument)) {
    $errors = libxml_get_errors();
    $errorMsg = implode("\n", array_map(fn($e) => $e->message, $errors));
    throw new RuntimeException("Failed to parse source XML: {$errorMsg}");
}
libxml_clear_errors();

4. 模板合并阶段的关键加固

在 ZIP 操作中，确保所有写入内容均为 UTF-8：

// 替换 targetZip->addFromString() 前的 XML 内容
$cleanXml = $targetDom->saveXML();
// 强制 UTF-8 声明（即使 DOMDocument 已设置）
if (strpos($cleanXml, '<?xml ') === 0) {
    $cleanXml = preg_replace('/<\?xml[^>]*\?>/', '<?xml version="1.0" encoding="UTF-8"?>', $cleanXml);
}
$targetZip->addFromString('word/document.xml', $cleanXml);