Dompdf PDF 生成教程：从 HTML 到 PDF 的正确实践-php教程-PHP中文网

Dompdf PDF 生成教程：从 HTML 到 PDF 的正确实践

本文旨在解决使用 Dompdf 生成 PDF 时常见的输出纯 HTML 而非渲染 PDF 的问题。核心在于理解 Dompdf 的工作流程，特别是 render() 方法的重要性。我们将详细介绍 Dompdf 的初始化、HTML 加载、纸张设置、关键的渲染步骤以及最终的输出与保存，并探讨高级配置选项和 HTML 优化技巧，确保您能成功地将 HTML 内容转换为高质量的 PDF 文档。

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 之前，对其进行最小化处理可以带来以下好处：

uBrand Logo生成器

uBrand Logo生成器是一款强大的AI智能LOGO设计工具。

查看详情

减少文件大小：移除不必要的空格、换行符和注释，可以稍微减小 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">
            &copy; ' . 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 文档。

以上就是Dompdf PDF 生成教程：从 HTML 到 PDF 的正确实践的详细内容，更多请关注php中文网其它相关文章！