在当今数字化飞速发展的时代，电子发票（e-invoicing）已成为企业间交易的常态，尤其是在欧洲，ZUGFeRD、XRechnung 和 Factur-X 等标准被广泛采用。这些标准定义了发票数据的 XML 结构，旨在实现自动化处理。然而，对于人类而言，直接阅读和理解这些密密麻麻的 XML 代码无疑是一项艰巨的任务。无论是为了客户查看、内部审计还是法规遵循，我们都需要将这些机器友好的数据转换成直观、易读的 HTML 页面或标准的 PDF 文档。手动解析 XML、设计布局、然后生成 PDF，这不仅耗时耗力，而且极易出错，成为许多 PHP 开发者在处理电子发票时的一大痛点。
幸运的是，PHP 社区为我们提供了一个优雅的解决方案：horstoeko/zugferdvisualizer。这个库是专门为可视化 ZUGFeRD、XRechnung 和 Factur-X 文档而设计的。它不是一个孤立的工具，而是与 horstoeko/zugferd（用于读取和处理 ZUGFeRD XML）和 mPdf（强大的 PDF 生成库）紧密集成，形成了一套完整的电子发票可视化工作流。通过它，我们可以轻松地将复杂的电子发票 XML 数据，快速转换为美观的 HTML 页面，并进一步生成可打印的 PDF 文件，彻底告别手动解析和排版的烦恼。
使用 Composer 轻松安装
使用 Composer 安装 horstoeko/zugferdvisualizer 非常简单。只需要在你的项目中运行以下命令，Composer 就会自动处理所有依赖项的下载和加载：
composer require horstoeko/zugferdvisualizer
这个命令会把 horstoeko/zugferdvisualizer 及其所需的 horstoeko/zugferd 和 mPdf 等依赖一并安装到你的 vendor 目录中，让你能够立即开始使用。
核心功能与使用示例
安装完成后，我们就可以开始体验 horstoeko/zugferdvisualizer 的强大功能了。
1. 从 XML 生成 HTML 标记
如果你只需要将电子发票 XML 渲染成 HTML 并在网页上显示，以下代码片段展示了如何使用内置模板轻松实现：
use horstoeko\zugferd\ZugferdDocumentReader; use horstoeko\zugferdvisualizer\ZugferdVisualizer; require dirname(__FILE__) . "/../vendor/autoload.php"; $document = ZugferdDocumentReader::readAndGuessFromFile(dirname(__FILE__) . "/invoice_1.xml"); $visualizer = new ZugferdVisualizer($document); $visualizer->setDefaultTemplate(); // 使用内置默认模板 echo $visualizer->renderMarkup(); // 输出 HTML 字符串
2. 从 XML 生成 PDF 文件
更常见的情况是，我们需要将电子发票导出为 PDF 文件。horstoeko/zugferdvisualizer 结合 mPdf 库，让这一过程变得轻而易举：
use horstoeko\zugferd\ZugferdDocumentReader;
use horstoeko\zugferdvisualizer\ZugferdVisualizer;
require dirname(__FILE__) . "/../vendor/autoload.php";
$document = ZugferdDocumentReader::readAndGuessFromFile(dirname(__FILE__) . "/invoice_1.xml");
$visualizer = new ZugferdVisualizer($document);
$visualizer->setDefaultTemplate();
$visualizer->setPdfFontDefault("courier"); // 设置 PDF 默认字体
$visualizer->renderPdfFile(dirname(__FILE__) . "/invoice_1.pdf"); // 生成 PDF 文件你也可以通过 renderPdf() 方法获取 PDF 文件的二进制字符串，方便进行进一步处理，例如直接在浏览器中输出或通过邮件发送。
3. 高度定制化：自定义渲染器与 PDF 选项
horstoeko/zugferdvisualizer 提供了极高的灵活性。如果你对内置模板不满意，可以实现 ZugferdVisualizerMarkupRendererContract 接口来创建自己的渲染器，完全掌控 HTML 的输出样式。
// 示例：使用自定义渲染器
$visualizer->setRenderer(new MyOwnRenderer());
$visualizer->setTemplate('/assets/myowntemplate.tmpl');此外，你还可以通过回调函数对底层 mPdf 实例进行精细配置，例如设置 PDF 的纸张大小、方向、版本，甚至引入自定义字体，以满足品牌或特殊排版的需求：
use Mpdf\Mpdf;
$visualizer->setPdfPreInitCallback(function (array $config, ZugferdVisualizer $visualizer) {
$config["orientation"] = "L"; // 横向 PDF
return $config;
});
$visualizer->setPdfRuntimeInitCallback(function (Mpdf $mpdf, ZugferdVisualizer $visualizer) {
$mpdf->pdf_version = "1.7"; // 设置 PDF 版本
});
// 添加自定义字体目录和字体数据
$visualizer->addPdfFontDirectory('/var/fonts/');
$visualizer->addPdfFontData('comicsans', 'R', 'comic.ttf');
$visualizer->setPdfFontDefault("comicsans");这些强大的定制功能，确保了生成的电子发票可视化效果能够完美契合你的业务需求和设计风格。
优势与实际应用
horstoeko/zugferdvisualizer 带来的优势是显而易见的：
- 简化复杂性： 将复杂的 XML 电子发票数据转化为人类可读的 HTML 或 PDF，大大降低了理解和处理的难度。
- 提升效率： 自动化了发票的可视化过程，节省了大量手动排版和转换的时间。
- 增强用户体验： 为客户和内部员工提供清晰、专业的发票视图，提升了整体满意度。
- 高度可定制： 从模板到 PDF 选项，几乎所有方面都可以根据需求进行定制，满足个性化和品牌化的要求。
- 无缝集成： 作为 Composer 包，它能轻松集成到任何 PHP 项目中，尤其是与 Laravel 等框架结合使用时，更是如虎添翼。
在实际应用中，你可以将它用于：
- ERP/会计系统： 生成用户友好的电子发票预览和打印件。
- 客户门户： 让客户在线查看其电子发票的 HTML 版本，或下载 PDF。
- 自动化流程： 在生成电子发票 XML 后，自动生成对应的 PDF 版本并存档或发送。
结语
horstoeko/zugferdvisualizer 不仅仅是一个库，它更是一个解决电子发票可视化痛点的利器。它将繁琐的 XML 解析和 PDF 生成工作封装起来，以简洁的 API 呈现给开发者，让我们能够专注于业务逻辑，而无需深陷于底层细节。如果你正在处理 ZUGFeRD、XRechnung 或 Factur-X 格式的电子发票，并希望以更高效、更优雅的方式将其可视化，那么 horstoeko/zugferdvisualizer 绝对值得你尝试。现在就通过 Composer 将它引入你的项目，体验电子发票可视化的全新境界吧！
