登录
首页 >  文章 >  php教程

Dompdf生成PDF教程：HTML转文档指南

时间：2025-10-17 17:18:35 332浏览 收藏

推广推荐
免费电影APP ➜
支持 PC / 移动端，安全直达

还在为HTML转PDF烦恼？本文为你提供一份详尽的Dompdf生成PDF教程，助你轻松将网页内容转化为可打印的精美文档。我们将深入解析Dompdf的核心流程，重点强调`render()`方法的重要性，避免生成纯文本HTML的常见错误。通过代码示例，手把手教你配置Dompdf选项，优化生成过程，包括启用HTML5解析器、处理远程资源和字体配置，确保PDF质量。更有高级技巧，教你封装可复用的函数，进行HTML最小化，提升性能。无论是生成报告、发票还是其他可打印文档，本教程都能帮你掌握Dompdf，高效完成PDF生成任务。

Dompdf生成PDF教程：从HTML到可打印文档的正确姿势

本文详细阐述了使用Dompdf库将HTML内容转换为PDF文件的正确方法。核心在于理解Dompdf的工作流程，特别是调用render()方法将加载的HTML渲染成PDF内部结构，再通过output()获取二进制数据。教程将提供完整的代码示例，并介绍如何配置Dompdf选项以优化生成过程，解决常见的输出纯文本HTML而非PDF的问题，确保生成高质量、可打印的PDF文档。

Dompdf PDF生成核心流程解析

在使用Dompdf将HTML内容转换为PDF时，一个常见的误区是忘记调用render()方法。render()是Dompdf将加载的HTML解析并渲染成内部PDF结构的关键步骤。如果缺少此步骤，output()方法将无法生成有效的PDF二进制数据，而是可能返回未经处理的HTML文本，导致打开文件时显示为纯文本HTML。

Dompdf生成PDF的基本流程如下：

  1. 实例化Dompdf对象：创建Dompdf实例，并可选地传入配置选项。
  2. 加载HTML内容：使用loadHtml()方法将待转换的HTML字符串加载到Dompdf实例中。
  3. 设置纸张大小和方向：通过setPaper()方法指定PDF的纸张大小（如'A4'）和方向（'portrait'或'landscape'）。
  4. 渲染HTML：调用render()方法执行HTML到PDF的渲染过程。这是将HTML结构和样式转换为PDF可视元素的核心步骤。
  5. 获取PDF输出：使用output()方法获取生成的PDF二进制数据。
  6. 保存或流式传输：将获取到的PDF数据保存到文件系统或直接通过HTTP响应流式传输给用户。

以下是一个基本的Dompdf使用示例，展示了正确的PDF生成流程：

<?php

require_once 'vendor/autoload.php'; // 确保Dompdf已通过Composer安装并加载

use Dompdf\Dompdf;
use Dompdf\Options;

// 1. 准备HTML内容
$htmlContent = '
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8">
        <title>我的PDF文档</title>
        <style>
            body { font-family: DejaVu Sans, sans-serif; } /* 确保支持中文，需要配置字体 */
            h1 { color: #333; }
            p { font-size: 14px; line-height: 1.5; }
        </style>
    </head>
    <body>
        <h1>欢迎来到我的PDF</h1>
        <p>这是一个使用Dompdf从HTML生成的示例PDF文档。</p>
        <p>我们可以包含各种HTML元素，如列表、表格、图片等。</p>
        <ul>
            <li>列表项1</li>
            <li>列表项2</li>
        </ul>
        <p>当前时间：' . date('Y-m-d H:i:s') . '</p>
    </body>
    </html>
';

// 2. 配置Dompdf选项
$options = new Options();
$options->set('isHtml5ParserEnabled', true); // 启用HTML5解析器，通常更快
$options->set('isRemoteEnabled', true);      // 允许加载远程资源（图片、CSS等）
// 如果需要支持中文等非拉丁字符，可能需要设置字体目录
// $options->set('fontDir', '/path/to/fonts');
// $options->set('fontCache', '/path/to/font/cache');

// 3. 实例化Dompdf
$dompdf = new Dompdf($options);

// 4. 加载HTML
$dompdf->loadHtml($htmlContent);

// 5. 设置纸张大小和方向
$dompdf->setPaper('A4', 'portrait'); // A4纸张，纵向

// 6. 渲染HTML到PDF
$dompdf->render();

// 7. 获取PDF二进制数据
$pdfOutput = $dompdf->output();

// 8. 保存PDF文件或流式传输
$fileName = 'example_document.pdf';
file_put_contents($fileName, $pdfOutput);
echo "PDF文件已成功生成并保存为: " . $fileName;

// 或者直接流式传输到浏览器
// header('Content-Type: application/pdf');
// header('Content-Disposition: attachment; filename="' . $fileName . '"');
// echo $pdfOutput;

?>

Dompdf高级配置与优化

Dompdf提供了丰富的配置选项，可以通过Dompdf\Options类进行设置，以满足不同的需求。以下是一些常用且重要的选项：

  • isHtml5ParserEnabled (boolean)：是否启用HTML5解析器。启用后，Dompdf在解析HTML时会更符合现代Web标准，并且通常能提供更好的性能。建议设置为true。
  • isRemoteEnabled (boolean)：是否允许Dompdf访问远程URL以加载图片、CSS等资源。如果HTML中包含外部链接的图片或样式表，需要设置为true。出于安全考虑，如果不需要，建议保持为false。
  • isPhpEnabled (boolean)：是否允许HTML中的PHP代码执行。默认通常为false，出于安全考虑，一般不建议在HTML模板中直接执行PHP。
  • isJavascriptEnabled (boolean)：是否启用JavaScript解析。Dompdf对JavaScript的支持非常有限，通常不建议启用。
  • isFontSubsettingEnabled (boolean)：是否启用字体子集化。启用后，Dompdf只会嵌入PDF中实际使用的字体字符，可以减小PDF文件大小。
  • fontDir (string)：指定自定义字体文件的目录。如果需要使用Dompdf默认不支持的字体（如中文字体），需要将字体文件（TTF格式）放置在此目录，并使用font-family在CSS中引用。
  • fontCache (string)：指定字体缓存目录。
  • *调试选项 (debug)**：如debugPng、debugKeepTemp、debugCss、debugLayout等。这些选项在开发和调试阶段非常有用，可以帮助诊断渲染问题。在生产环境中应禁用。

示例：封装为可复用的函数

为了提高代码的可维护性和复用性，可以将Dompdf的PDF生成逻辑封装到一个函数或类方法中。这也有助于统一管理配置和错误处理。

<?php

require_once 'vendor/autoload.php';

use Dompdf\Dompdf;
use Dompdf\Options;

/**
 * 将HTML字符串转换为PDF二进制数据。
 *
 * @param string $html 待转换的HTML内容。
 * @param string $size 纸张大小，如 'A4', 'Letter'。
 * @param string $orientation 纸张方向，'portrait' (纵向) 或 'landscape' (横向)。
 * @return string PDF二进制数据。
 * @throws Exception 如果PDF生成失败。
 */
function htmlToPdf(string $html, string $size = 'A4', string $orientation = 'portrait'): string
{
    // 配置Dompdf选项
    $options = new Options([
        'isHtml5ParserEnabled'    => true,  // 启用HTML5解析器
        'isRemoteEnabled'         => true,  // 允许加载远程资源
        'isPhpEnabled'            => false, // 禁止HTML中的PHP执行
        'isJavascriptEnabled'     => false, // 禁止JavaScript执行
        'isFontSubsettingEnabled' => true,  // 启用字体子集化以减小文件大小
        // 如果需要自定义字体，请在此处配置字体目录
        // 'fontDir'                 => __DIR__ . '/fonts',
        // 'fontCache'               => __DIR__ . '/font_cache',
        // 'defaultFont'             => 'SimSun', // 默认字体，确保已加载
        // 调试选项，生产环境应禁用
        // 'debugPng'                => false,
        // 'debugKeepTemp'           => false,
        // 'debugCss'                => false,
    ]);

    $dompdf = new Dompdf($options);

    // 优化HTML：移除不必要的空白字符，减小HTML大小，有时也能避免渲染问题
    $minimizedHtml = minimizeHtml($html);
    $dompdf->loadHtml($minimizedHtml);

    $dompdf->setPaper($size, $orientation);

    // 核心步骤：渲染HTML
    $dompdf->render();

    // 获取PDF输出
    $pdfOutput = $dompdf->output();

    if (empty($pdfOutput)) {
        throw new Exception("Dompdf未能生成有效的PDF输出。");
    }

    return $pdfOutput;
}

/**
 * 最小化HTML源，移除不必要的空白字符。
 *
 * @param string $html
 * @return string
 */
function minimizeHtml(string $html): string
{
    return preg_replace(
        [
            '/\>[^\S ]+/s',  // 剥离标签后的空白字符，除了空格
            '/[^\S ]+\</s',  // 剥离标签前的空白字符，除了空格
            '/(\s)+/s'       // 缩短多个空白字符序列
        ],
        [
            '>',
            '<',
            '\\1'
        ],
        $html
    );
}

// 示例用法：
try {
    $sampleHtml = '
        <!DOCTYPE html>
        <html>
        <head>
            <meta charset="utf-8">
            <title>优化后的PDF</title>
            <style>
                body { font-family: sans-serif; margin: 20px; }
                h1 { color: #0056b3; }
                p { font-size: 1em; }
            </style>
        </head>
        <body>
            <h1>这是一个经过优化的PDF文档</h1>
            <p>通过封装函数和HTML最小化，我们可以更高效地生成PDF。</p>
            <img src="https://via.placeholder.com/150" alt="Placeholder Image">
        </body>
        </html>
    ';

    $pdfData = htmlToPdf($sampleHtml, 'A4', 'portrait');
    $outputPath = 'optimized_document.pdf';
    file_put_contents($outputPath, $pdfData);
    echo "优化后的PDF已保存到: " . $outputPath . "\n";

} catch (Exception $e) {
    echo "PDF生成失败: " . $e->getMessage() . "\n";
}

?>

注意事项与最佳实践

  1. 字体支持：Dompdf默认支持的字体有限，特别是对于中文、日文、韩文等非拉丁字符，需要手动配置字体。通常的做法是将TTF格式的字体文件放置在指定目录，并在CSS中使用font-family引用。Dompdf还提供了load_font.php脚本来帮助安装字体。
  2. CSS兼容性：Dompdf对CSS3的支持不如现代浏览器全面。在设计HTML模板时，应尽量使用基本的CSS2.1属性，并避免复杂的布局（如Flexbox、Grid）或高级CSS选择器。
  3. 图片与资源路径：如果HTML中包含本地图片，确保路径是正确的绝对路径或相对于脚本执行位置的相对路径。如果isRemoteEnabled为true，Dompdf可以加载远程图片。
  4. HTML有效性：确保输入的HTML是格式良好且有效的。无效的HTML可能导致Dompdf解析错误或渲染异常。
  5. 性能优化：
    • HTML最小化：如minimizeHtml函数所示，移除不必要的空白字符可以减小HTML大小，从而加快Dompdf的解析速度。
    • 禁用不必要的选项：例如，如果HTML不包含JavaScript，就将isJavascriptEnabled设置为false。
    • 字体子集化：isFontSubsettingEnabled设置为true可以显著减小PDF文件大小。
  6. 错误处理：在实际应用中，应包含适当的错误处理机制，捕获Dompdf可能抛出的异常，并向用户提供有意义的反馈。

总结

Dompdf是一个功能强大的HTML到PDF转换库，但正确使用它需要理解其核心工作流程。关键在于不要遗漏render()方法，它是将HTML内容转换为PDF内部表示的必要步骤。通过合理配置Options，封装生成逻辑，并注意字体、CSS兼容性及性能优化，可以高效且稳定地生成高质量的PDF文档。遵循本教程中的指导和最佳实践，将有助于您成功地利用Dompdf解决PDF生成任务。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~

相关阅读
更多>
最新阅读
更多>
课程推荐
更多>