Laravel PDF 生成不再困难

在 Web 上生成 PDF 文档一直是个相当棘手的问题。想想看你有多少次试图排版出完美的发票或报告，结果却发现字体移位、表格错乱、图片完全消失了。通常的选择无非是 wkhtmltopdf 这类复杂的系统工具（需要服务器配置）和付费的云服务。

如果你使用 Laravel 技术栈，有一个久经考验的解决方案——Barry van den Heuvel 的 laravel-dompdf 包。它是 Dompdf 库的封装，可以用你熟悉的 Blade 模板直接生成 PDF 文件。无需额外的服务器依赖，纯 PHP 即可。

底层原理

这个项目的核心功能只有一个：将 Laravel 的强大能力与 Dompdf 引擎连接起来。主要特点是，你不需要学习新的文档布局语法。你只需创建一个普通的 View，传递数据给它，剩下的由包来处理渲染。

有趣的是，这个包不仅支持标准 Laravel，还支持 Lumen。如果你将文档生成抽取为独立的微服务，这会非常有用。

实际使用方式

通过 Composer 安装是标准流程：

composer require barryvdh/laravel-dompdf

安装完成后，你可以通过 Pdf Facade 来操作。创建文件的最简单示例如下：

use Barryvdh\DomPDF\Facade\Pdf;

$pdf = Pdf::loadView('emails.invoice', ['order' => $order]);
return $pdf->download('invoice.pdf');

loadView 方法会加载你的 Blade 文件，向其中传递变量，然后生成一个对象，你可以立即用它来让用户下载或通过 stream() 在浏览器中显示。

灵活的页面设置

很多时候你需要直接在代码中更改页面方向或纸张格式。例如，宽表格更适合横向布局：

Pdf::loadHTML($html)
    ->setPaper('a4', 'landscape')
    ->setWarnings(false)
    ->save('report.pdf');

顺便说一句，如果你需要将文件保存到磁盘而不是发送给用户，save() 方法可以一步完成。

PDF/A-3b 支持与电子发票

最新版本（3.x）增加了对 PDF/A-3b 标准 的支持。这对于长期文档归档至关重要。但有一个限制：这个标准要求所有字体都必须嵌入文件中。标准的 Helvetica 或 Times 字体不行——你需要使用类似 DejaVu Sans 的字体。

对于从事财务自动化的开发者，这个包现在支持 Zugferd 和 Factur-X 格式。这就是将包含发票数据的 XML 文件直接嵌入到 PDF 中。大致是这样的：

$pdf = Pdf::loadView('invoice', $data)->setPdfA();

// Добавляем метаданные для Factur-X
$pdf->setAdditionalXmpRdf($xmlMetadata);

// Прикрепляем сам XML
$pdf->addEmbeddedFile(
    storage_path('invoices/factur-x.xml'),
    'factur-x.xml',
    'Factur-X Invoice',
    'text/xml'
);

排版技巧

Dompdf 不是一个完整的浏览器引擎。它能很好地处理 CSS 2.1 和部分 CSS 3 属性，但不要尝试使用 Flexbox 或 Grid。经典表格和浮动布局才是最佳选择。

两件事可以为你节省大量时间：

1. 始终在模板中指定编码：<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>。没有这个，西里尔字母会变成问号。
2. 对于分页，使用 CSS 属性 page-break-after: always。这是让打印机在你需要的地方开始新页面的最可靠方式。

是否值得使用

laravel-dompdf 是一个可靠的工作利器。它非常适合生成简单到中等复杂度的文档：发票、服务报告、简单的对账单。

主要优势在于简单。你不需要安装 Node.js、Puppeteer 或配置服务器二进制文件。在标准 PHP 主机上，开箱即用。

然而，如果你需要渲染复杂的 JavaScript 图表，或者你的布局大量使用现代 CSS 技巧，Dompdf 可能会力不从心。这种情况下，最好考虑基于 Chromium 的工具。但对于 90% 的后端开发任务来说，这个包已经足够了。

该项目活跃且维护积极（GitHub 上超过 7,000 颗星），由 Laravel 社区最知名的贡献者之一支持。如果你还没尝试过——现在正是收藏它的好时机。