10分钟搞定动态PDF生成：laravel-dompdf与数据库交互实战指南

2026-02-06 05:24:41作者：平淮齐Percy

你是否还在为PHP项目中动态生成PDF报表而烦恼？客户要求的合同自动填充、订单确认函实时生成、数据统计报表导出等需求，往往需要开发者编写大量繁琐代码。本文将以laravel-dompdf为核心，通过3个实战场景带你掌握从数据库动态填充PDF模板的完整流程，无需复杂配置即可实现企业级PDF生成功能。

技术准备与环境配置

laravel-dompdf是基于Dompdf库的Laravel封装，通过ServiceProvider.php实现服务注册，支持视图渲染、文件输出和流式传输等功能。使用前需通过Composer安装依赖：

composer require barryvdh/laravel-dompdf

配置文件位于config/dompdf.php，关键设置包括：

chroot: 安全根目录限制，默认设为项目根目录
allowed_protocols: 允许的数据访问协议，默认支持file://和http://
enable_remote: 是否允许加载远程资源，生成动态PDF时建议开启

核心实现原理

PDF生成流程主要通过PDF.php类实现，核心方法包括：

// 加载HTML内容
public function loadHTML(string $string, ?string $encoding = null): self

// 加载视图文件并传递数据
public function loadView(string $view, array $data = [], array $mergeData = [], ?string $encoding = null): self

// 输出PDF文件
public function output(array $options = []): string

// 下载PDF文件
public function download(string $filename = 'document.pdf'): Response

// 保存PDF到服务器
public function save(string $filename, ?string $disk = null): self

数据流向如图所示：

graph LR
    A[数据库查询] --> B[数据处理]
    B --> C[视图渲染]
    C --> D[PDF生成]
    D --> E[输出/下载/保存]

实战场景1：用户订单确认函

模板设计

创建订单模板文件resources/views/pdf/order.blade.php：

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <style>
        .order-header { border-bottom: 2px solid #333; padding-bottom: 10px; margin-bottom: 20px; }
        .order-info { margin-bottom: 20px; }
        .product-table { width: 100%; border-collapse: collapse; margin-top: 20px; }
        .product-table th, .product-table td { border: 1px solid #ddd; padding: 8px; text-align: left; }
    </style>
</head>
<body>
    <div class="order-header">
        <h2>订单确认函</h2>
    </div>
    
    <div class="order-info">
        <p>订单编号: {{ $order->order_number }}</p>
        <p>客户名称: {{ $order->customer_name }}</p>
        <p>下单时间: {{ $order->created_at->format('Y-m-d H:i') }}</p>
    </div>
    
    <table class="product-table">
        <thead>
            <tr>
                <th>商品名称</th>
                <th>单价</th>
                <th>数量</th>
                <th>小计</th>
            </tr>
        </thead>
        <tbody>
            @foreach($order->items as $item)
            <tr>
                <td>{{ $item->product_name }}</td>
                <td>¥{{ number_format($item->price, 2) }}</td>
                <td>{{ $item->quantity }}</td>
                <td>¥{{ number_format($item->price * $item->quantity, 2) }}</td>
            </tr>
            @endforeach
        </tbody>
        <tfoot>
            <tr>
                <td colspan="3" align="right">总计:</td>
                <td>¥{{ number_format($order->total_amount, 2) }}</td>
            </tr>
        </tfoot>
    </table>
</body>
</html>

控制器实现

use Barryvdh\DomPDF\Facade\Pdf;
use App\Models\Order;

public function generateOrderPdf($orderId)
{
    // 从数据库获取订单数据
    $order = Order::with('items')->findOrFail($orderId);
    
    // 加载视图并生成PDF
    $pdf = Pdf::loadView('pdf.order', compact('order'))
              ->setPaper('a4', 'portrait');
              
    // 可选：添加PDF元数据
    $pdf->addInfo([
        'Title' => "订单确认函 #{$order->order_number}",
        'Author' => 'Your Company Name',
        'Subject' => 'Order Confirmation'
    ]);
    
    // 下载PDF文件
    return $pdf->download("order_{$order->order_number}.pdf");
}

实战场景2：月度销售报表

对于包含图表的数据报表，可结合Chart.js生成Base64图像嵌入PDF：

<!-- 在Blade模板中 -->
<div class="chart-container">
    <canvas id="salesChart" width="600" height="300"></canvas>
</div>

<script>
    // 使用Chart.js生成图表
    const ctx = document.getElementById('salesChart').getContext('2d');
    const salesChart = new Chart(ctx, {
        type: 'bar',
        data: {
            labels: {!! json_encode($labels) !!},
            datasets: [{
                label: '销售额',
                data: {!! json_encode($salesData) !!},
                backgroundColor: 'rgba(54, 162, 235, 0.5)'
            }]
        }
    });
    
    // 将图表转换为Base64图像
    document.getElementById('chartImage').src = salesChart.toBase64Image();
</script>

性能优化策略

数据缓存：对于频繁生成的报表，使用Laravel缓存减少数据库查询：

$salesData = Cache::remember("monthly_sales_{$year}_{$month}", 3600, function () use ($year, $month) {
    return Sale::whereYear('created_at', $year)
               ->whereMonth('created_at', $month)
               ->get();
});

分批次处理：大数据量PDF生成时采用队列异步处理：

use Illuminate\Support\Facades\Queue;
use App\Jobs\GenerateLargePdfReport;

public function queueLargeReport()
{
    Queue::push(new GenerateLargePdfReport(Auth::user()->id, request()->input('parameters')));
    return response()->json(['message' => '报表生成任务已加入队列']);
}

配置优化：在config/dompdf.php中设置字体缓存路径：

'font_cache' => storage_path('fonts'),

常见问题解决方案

中文显示乱码：需在配置文件中添加中文字体支持，将字体文件放入storage/fonts目录
图片无法加载：确保图片路径正确或使用绝对URL，本地图片需设置chroot参数
内存溢出：对于超大数据集，通过tests/PdfTest.php中的分批次渲染方法优化

项目测试与验证

测试用例位于tests/PdfTest.php，包含下载、流式传输和文件保存等功能验证：

public function testDownload()
{
    $pdf = Facade\Pdf::loadHTML('<h1>Test</h1>');
    $response = $pdf->download('test.pdf');
    
    $this->assertInstanceOf(Response::class, $response);
    $this->assertEquals('application/pdf', $response->headers->get('Content-Type'));
}

可通过PHPUnit运行测试确保核心功能正常：

vendor/bin/phpunit tests/PdfTest.php

总结与扩展应用

通过laravel-dompdf实现动态PDF生成的核心优势在于：

与Laravel视图系统无缝集成，支持Blade模板语法
通过PDF.php提供的方法链简化操作流程
灵活的输出选项，支持下载、流式查看和服务器保存

扩展应用场景包括：

自动生成电子发票并发送邮件
生成带电子签名的法律文档
批量导出用户数据报表
动态生成产品说明书

完整项目代码可通过以下地址获取：

git clone https://gitcode.com/gh_mirrors/la/laravel-dompdf

掌握这些技巧后，你可以轻松应对各类动态PDF生成需求，为用户提供专业的文档导出体验。

laravel-dompdf

A DOMPDF Wrapper for Laravel

项目地址：https://gitcode.com/gh_mirrors/la/laravel-dompdf

登录后查看全文

项目优选

收起

kernel

deepin linux kernel

docs

OpenHarmony documentation | OpenHarmony开发者文档

🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解

Java

nop-entropy

Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统

喝着茶写代码！最易用的自托管一站式代码托管平台，包含Git托管，代码审查，团队协作，软件包和CI/CD。

kernel

openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。

349

200

pytorch

Ascend Extension for PyTorch

无需学习 Kubernetes 的容器平台，在 Kubernetes 上构建、部署、组装和管理应用，无需 K8s 专业知识，全流程图形化管理