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

登录后查看全文

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

技术准备与环境配置

核心实现原理

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

模板设计

控制器实现

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

性能优化策略

常见问题解决方案

项目测试与验证

总结与扩展应用

热门内容推荐

最新内容推荐

项目优选

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

技术准备与环境配置

核心实现原理

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

模板设计

控制器实现

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

性能优化策略

常见问题解决方案

项目测试与验证

总结与扩展应用

相关内容推荐

热门内容推荐

最新内容推荐

项目优选