TCPDF Datamatrix 生成 XML 字符串时出现编码错误的解决方案

TCPDF 的 Datamatrix 编码器存在底层实现缺陷，对含尖括号的 XML 字符串（如 G6Y0A3）会错误插入 GS1 格式控制字符（如 [)>06、），导致扫码结果异常；根本原因在于 datamatrix.php 中 getHighLevelEncoding() 函数未正确处理结构化数据边界，需手动预编码规避。

tcpdf 的 datamatrix 编码器存在底层实现缺陷，对含尖括号的 xml 字符串（如 `g6y0a3`）会错误插入 gs1 格式控制字符（如 `[)>06`、``），导致扫码结果异常；根本原因在于 `datamatrix.php` 中 `gethighlevelencoding()` 函数未正确处理结构化数据边界，需手动预编码规避。

TCpdf 内置的 Datamatrix 编码模块（位于 tcpdf/include/barcodes/datamatrix.php）在解析输入字符串时，默认启用 GS1 模式（AIM ID Syntax），该模式将 、[) 等字符识别为 GS1 数据分隔符或功能字符，而非普通文本。当传入类似 G6Y0A3 的 XML 片段时，TCPDF 错误地将其解析为 GS1 结构化数据（例如误判 为应用标识符 AI(14)），从而注入额外的格式头（如 [)>06）和分隔符（如 ），最终导致扫码输出完全失真。

✅ 正确做法是：在调用 write2DBarcode() 前，对原始 XML 字符串进行 ASCII 兼容的无损编码，使其脱离 GS1 解析上下文。推荐使用 Base64 编码（安全、无特殊字符、广泛支持）：

$xml = '<AN14>G6Y0A3</AN14>'; $encoded = base64_encode($xml); // 输出: PEFOMTQ+RzZZMEEzPC9BTjE0Pg==  $pdf->write2DBarcode(     $encoded,      'DATAMATRIX',      124, 189, 66, 66,      ['border' => 0, 'padding' => 0, 'bgcolor' => [255, 255, 255]],      'N' );

扫码后，读取端需执行对应解码（如 base64_decode()）还原原始 XML。此方案绕过 TCPDF 的 GS1 自动识别逻辑，确保字节流被原样编码为 Datamatrix 符号。

⚠️ 注意事项：

• 不要使用 htmlspecialchars() 或 htmlentities() —— 它们引入 < 等实体，增大数据量且非标准；
• 避免手动添加空格（如 G6Y 0A3）等临时 hack，破坏数据语义且不可靠；
• 若必须保留可读性（如调试），可在 Base64 后追加校验字段（如 base64_encode($xml) . ‘|’ . md5($xml)），但需同步更新解码逻辑；
• 此问题已在 TCPDF github 仓库被多次报告（#142、#287），但截至 v6.6.x 仍未修复，属已知限制（not a bug in user code, but in library logic）。

? 总结：TCPDF 的 Datamatrix 编码器不适用于直接编码含 的结构化文本。Base64 预编码是当前最稳定、兼容性最佳的工程实践。生产环境务必在生成端编码、扫码端解码，并通过单元测试验证往返一致性（encode → barcode → scan → decode → match）。