Dompdf PDF 生成核心流程
在使用 dompdf 将 html 内容转换为 pdf 时，一个常见的错误是忘记调用 render() 方法。render() 是 dompdf 将加载的 html 内容解析并渲染成 pdf 格式的关键步骤。如果缺少此步骤，您最终可能会得到原始的 html 文本而不是一个格式化的 pdf 文件。
以下是使用 Dompdf 生成 PDF 的正确流程和基本代码示例：
- 初始化 Dompdf 实例：首先需要创建 Dompdf 对象。通常会传入一个 Options 对象来配置 Dompdf 的行为。
- 加载 HTML 内容：使用 loadHtml() 方法将待转换的 HTML 字符串加载到 Dompdf 实例中。
- 设置 PDF 纸张和方向：通过 setPaper() 方法指定 PDF 的纸张大小（如 'A4'）和方向（如 'portrait' 或 'landscape'）。
- 渲染 PDF 内容：这是最关键的一步。调用 render() 方法，Dompdf 会在此阶段处理 HTML，将其转换为可打印的 PDF 结构。
-
输出或保存 PDF：
- 使用 output() 方法获取 PDF 的二进制内容，通常用于保存到文件。
- 使用 stream() 方法直接将 PDF 发送到浏览器，通常用于在线预览或下载。
基本示例代码：
<?php
require_once 'vendor/autoload.php'; // 确保 Dompdf 已通过 Composer 加载
use DompdfDompdf;
use DompdfOptions;
// 假设这是您的 HTML 内容
$htmlContent = '
<h1>Dompdf PDF 生成示例</h1>
<p>这是一个测试段落，用于演示如何使用 Dompdf 将 HTML 转换为 PDF。</p>
<img src="https://via.placeholder.com/150" alt="占位图">
<ul>
<li>列表项 1</li>
<li>列表项 2</li>
</ul>
';
// 1. 初始化 Dompdf 选项
$options = new Options();
$options->set('isHtml5ParserEnabled', true); // 启用 HTML5 解析器，通常更快
$options->set('isRemoteEnabled', true); // 允许加载远程资源（如图片、CSS）
// 2. 初始化 Dompdf 实例
$dompdf = new Dompdf($options);
// 3. 加载 HTML 内容
$dompdf->loadHtml($htmlContent);
// 4. 设置 PDF 纸张大小和方向
$dompdf->setPaper('A4', 'portrait'); // A4 纸张，纵向
// 5. 渲染 PDF 内容 (关键步骤！)
$dompdf->render();
// 6. 输出或保存 PDF
// 方式一：直接输出到浏览器
// $dompdf->stream("document.pdf", ["Attachment" => false]); // Attachment => false 表示在浏览器中打开
// 方式二：获取 PDF 二进制内容并保存到文件
$pdfOutput = $dompdf->output();
$filePath = __DIR__ . '/generated_document.pdf'; // 保存路径
file_put_contents($filePath, $pdfOutput);
echo "PDF 已成功生成并保存到： " . $filePath;
?>在上述代码中，$dompdf-youjiankuohaophpcnrender(); 是确保 HTML 被正确处理并转换为 PDF 格式的核心指令。
Dompdf 配置选项详解
Dompdf 提供了丰富的配置选项，允许您精细控制 PDF 的生成过程。这些选项通过 DompdfOptions 类进行设置。以下是一些常用的配置项及其说明：
立即学习“前端免费学习笔记（深入）”；
use DompdfOptions;
$options = new Options([
// 'logOutputFile' => 'data/log.htm', // 日志文件路径
'isPhpEnabled' => false, // 是否允许在 HTML 中执行 PHP 代码 (出于安全考虑通常禁用)
'isRemoteEnabled' => true, // 是否允许加载远程资源 (如外部 CSS、图片)
'isJavascriptEnabled' => false, // 是否允许在 HTML 中执行 JavaScript (通常禁用，Dompdf 不支持 JS 渲染)
'isHtml5ParserEnabled' => true, // 启用 HTML5 解析器，通常能提高解析速度和兼容性
'isFontSubsettingEnabled' => false, // 是否启用字体子集化，减少文件大小
'debugPng' => false, // 调试 PNG 图像
'debugKeepTemp' => false, // 调试时保留临时文件
'debugCss' => false, // 调试 CSS 解析
'debugLayout' => false, // 调试布局计算
'debugLayoutLines' => false, // 调试布局行
'debugLayoutBlocks' => false, // 调试布局块
'debugLayoutInline' => false, // 调试内联布局
'debugLayoutPaddingBox' => false, // 调试内边距框
// 'pdfBackend' => 'CPDF', // PDF 后端，默认为 CPDF
]);
$domPdf = new Dompdf($options);关键配置项说明：
- isHtml5ParserEnabled：强烈建议设置为 true。它能更好地处理现代 HTML 结构，提高解析效率和准确性。
- isRemoteEnabled：如果您需要在 HTML 中引用外部图片（如 CDN 上的图片）或外部样式表，必须将其设置为 true。但请注意潜在的安全风险。
- isPhpEnabled / isJavascriptEnabled：出于安全和性能考虑，通常建议将这两个选项设置为 false。Dompdf 并非一个完整的浏览器环境，不支持复杂的 JavaScript 交互或服务器端 PHP 执行。
优化 HTML 输入：HTML 最小化
在将 HTML 传递给 Dompdf 之前，对其进行最小化处理可以带来以下好处：
- 减少文件大小：移除不必要的空格、换行符和注释，可以稍微减小 HTML 字符串的体积。
- 提高解析效率：更紧凑的 HTML 有助于 Dompdf 更快地解析内容。
- 避免潜在布局问题：有时多余的空白字符可能会在某些边缘情况下影响布局，最小化可以减少这类情况。
以下是一个简单的 HTML 最小化函数示例，它使用正则表达式移除标签之间和标签内部的多余空白字符：
/**
* 最小化 HTML 源代码。
* 移除标签后的空白、标签前的空白以及多个连续的空白字符。
*
* @param string $html 原始 HTML 字符串
* @return string 最小化后的 HTML 字符串
*/
public function minimizeHtml(string $html): string
{
return preg_replace(
[
'/>[^S ]+/s', // 移除标签后的非空白字符，除了空格
'/[^S ]+</s', // 移除标签前的非空白字符，除了空格
'/(s)+/s' // 缩短多个连续的空白字符
],
[
'>',
'<',
'\1'
],
$html
);
}在实际应用中，您可以在将 HTML 内容传递给 loadHtml() 方法之前，先调用此函数进行处理：
$minimizedHtml = $this->minimizeHtml($htmlContent); $dompdf->loadHtml($minimizedHtml);
完整示例与最佳实践
结合上述所有要素，我们可以构建一个更健壮、更专业的 PDF 生成方法：
<?php
require_once 'vendor/autoload.php';
use DompdfDompdf;
use DompdfOptions;
class PdfGenerator
{
/**
* 将 HTML 字符串转换为 PDF 二进制内容。
*
* @param string $html 待转换的 HTML 字符串
* @param string $size 纸张大小 (如 'A4', 'Letter')
* @param string $orientation 纸张方向 (如 'portrait', 'landscape')
* @return string PDF 的二进制内容
*/
public function htmlToPdf(string $html, string $size = 'A4', string $orientation = 'portrait'): string
{
// 1. 配置 Dompdf 选项
$options = new Options([
'isPhpEnabled' => false,
'isRemoteEnabled' => true, // 允许加载远程图片/CSS
'isJavascriptEnabled' => false,
'isHtml5ParserEnabled' => true,
'isFontSubsettingEnabled' => false,
// 调试选项通常在生产环境禁用
'debugPng' => false,
'debugKeepTemp' => false,
'debugCss' => false,
'debugLayout' => false,
]);
// 2. 初始化 Dompdf 实例
$domPdf = new Dompdf($options);
// 3. 最小化 HTML 内容并加载
$minimizedHtml = $this->minimizeHtml($html);
$domPdf->loadHtml($minimizedHtml);
// 4. 设置纸张大小和方向
$domPdf->setPaper($size, $orientation);
// 5. 渲染 PDF (核心步骤)
$domPdf->render();
// 6. 返回 PDF 的二进制内容
return $domPdf->output();
}
/**
* 最小化 HTML 源代码。
*
* @param string $html 原始 HTML 字符串
* @return string 最小化后的 HTML 字符串
*/
private function minimizeHtml(string $html): string
{
return preg_replace(
[
'/>[^S ]+/s', // strip whitespaces after tags, except space
'/[^S ]+</s', // strip whitespaces before tags, except space
'/(s)+/s' // shorten multiple whitespace sequences
],
[
'>',
'<',
'\1'
],
$html
);
}
}
// --- 使用示例 ---
$pdfGenerator = new PdfGenerator();
$sampleHtml = '
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>我的报告</title>
<style>
body { font-family: "DejaVu Sans", sans-serif; margin: 20px; }
h1 { color: #333; }
p { line-height: 1.5; }
.footer { text-align: center; margin-top: 50px; font-size: 0.8em; color: #666; }
</style>
</head>
<body>
<h1>Dompdf 生成的报告</h1>
<p>这份报告演示了 Dompdf 的强大功能，包括自定义样式和图片加载。</p>
<p>您可以轻松地将复杂的 HTML 页面转换为专业的 PDF 文档。</p>
<img src="https://via.placeholder.com/200x100?text=Logo" alt="示例Logo" style="width: 200px; height: 100px;">
<div class="footer">
© ' . date('Y') . ' Dompdf 教程
</div>
</body>
</html>
';
try {
$pdfContent = $pdfGenerator->htmlToPdf($sampleHtml, 'A4', 'portrait');
$outputPath = __DIR__ . '/professional_report.pdf';
file_put_contents($outputPath, $pdfContent);
echo "专业报告 PDF 已成功生成并保存到： " . $outputPath . "
";
// 也可以直接流式输出到浏览器
// header('Content-Type: application/pdf');
// header('Content-Disposition: inline; filename="professional_report.pdf"');
// echo $pdfContent;
} catch (Exception $e) {
echo "生成 PDF 时发生错误: " . $e->getMessage() . "
";
}
?>注意事项：
- 字体支持：Dompdf 对中文字体的支持可能需要额外配置。您可能需要嵌入支持中文的字体（如 DejaVu Sans，或通过 Dompdf 的字体工具添加自定义字体）并在 CSS 中指定。
- CSS 兼容性：Dompdf 对 CSS3 的支持有限，尤其是一些高级布局（如 Flexbox、Grid）可能无法完美渲染。建议使用传统的块级元素和浮动布局。
- 版本兼容性：上述代码基于 Dompdf v0.8.x 或更高版本。不同版本之间 API 可能略有差异，请查阅您所使用版本的官方文档。
- 错误处理：在实际应用中，务必添加适当的错误处理机制，例如 try-catch 块来捕获 Dompdf 在渲染过程中可能抛出的异常。
总结
正确使用 Dompdf 生成 PDF 的关键在于遵循其工作流程，尤其是不能遗漏 render() 方法。通过合理配置 Options，您可以控制 Dompdf 的行为，使其更好地适应您的需求。此外，对 HTML 内容进行最小化处理是一种良好的实践，有助于提高性能和稳定性。掌握这些核心概念和技巧，您将能够高效且准确地将 HTML 内容转换为高质量的 PDF 文档。
