Laravel 导出报价单 PDF：从 Blade 模板到文件下载

ComPDF 的个人博客 / 11 / 0 / 创建于 6小时前

AI摘要

【总结】本文属知识分享，介绍Laravel结合ComPDF实现报价单HTML转PDF的接入流程，强调数据与模板分离、中文输出验证、下载响应与权限校验，并给出同步调用示例及生产环境注意事项。

Laravel报价单从Blade模板到PDF下载示意

报价单导出看似只是把一组字段放进 PDF，真正容易卡住的是三件事：模板和数据没有分开、中文输出不符合预期，以及下载响应、访问权限和文件版本没有接好。

本文用一张教学报价单说明接入顺序。

报价单生成与核对流程

ComPDF负责把HTML或模板转换为PDF；报价数据、权限、文件命名和下载响应仍由Laravel应用负责。

先把报价数据和模板分开

不要在控制器里拼一整段HTML。先准备结构化数据，再交给Blade模板渲染：

$quote = [
    'number' => 'Q-2026-271',
    'customer' => '教学供应商丙',
    'currency' => 'CNY',
    'items' => [
        ['name' => '可调支架', 'quantity' => 7, 'unit_price' => 45.00],
    ],
];

return view('quotes.pdf', compact('quote'));

在 resources/views/quotes/pdf.blade.php 中，模板只负责展示已经校验过的数据：

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <style>body{font-family: sans-serif} table{width:100%;border-collapse:collapse} th,td{border:1px solid #bbb;padding:8px} .total{text-align:right}</style>
</head>
<body>
  <h1>报价单 {{ $quote['number'] }}</h1>
  <p>客户：{{ $quote['customer'] }}　币种：{{ $quote['currency'] }}</p>
  <table>
    <thead><tr><th>项目</th><th>数量</th><th>单价</th><th>小计</th></tr></thead>
    <tbody>
    @foreach ($quote['items'] as $item)
      <tr>
        <td>{{ $item['name'] }}</td>
        <td>{{ $item['quantity'] }}</td>
        <td>{{ number_format($item['unit_price'], 2) }}</td>
        <td>{{ number_format($item['quantity'] * $item['unit_price'], 2) }}</td>
      </tr>
    @endforeach
    </tbody>
  </table>
</body>
</html>

这个模板示例只演示字段和明细循环。生产环境还要按项目需要处理税额、舍入、页眉页脚和多页表格。

金额、数量和币种由应用校验。模板只负责展示，不能把“总价正确”交给视图自行猜测。

用Blade输出HTML，再调用HTML转PDF

Blade文档默认会转义变量，适合输出报价客户名称和明细。循环生成明细行时，仍应在保存报价前完成字段校验。

渲染好的HTML可交给ComPDF HTML转PDF接口。同步请求返回结果地址，文档列出的下载有效期为24小时，因此应及时下载。下面使用单份、小文件的同步调用；批量任务另按异步模式组织。

先在 .env 中配置 COMPDF_API_KEY，再在 config/services.php 的返回数组中加入配置。不要把密钥写进Blade或浏览器代码。

'compdf' => ['key' => env('COMPDF_API_KEY')],

以下片段放在已完成登录和报价查看权限检查的控制器方法里。方法中的 $quote 使用前面已经校验过的数据，HTTP请求使用Laravel提供的 Http 门面：

use Illuminate\Support\Facades\Http;

// 放入控制器方法内部：
$html = view('quotes.pdf', compact('quote'))->render();
$filename = 'Q-2026-271.pdf'; // 教学文件名；实际项目用已校验的编号
$key = config('services.compdf.key');
abort_unless(is_string($key) && $key !== '', 503, '尚未配置PDF服务');

$response = Http::timeout(120)
    ->withHeaders(['x-api-key' => $key])
    ->attach('file', $html, 'quote.html')
    ->post('https://api-server.compdf.com/server/v2/process/html/pdf', [
        'language' => 2,
    ])->throw()->json();

$data = $response['data'] ?? [];
$url = $data['downloadUrl'] ?? null;
abort_unless(
    (string) ($response['code'] ?? '') === '200'
    && ($data['status'] ?? '') === 'success'
    && is_string($url) && $url !== '',
    502, '未取得PDF结果，请检查转换状态'
);

// 本例只下载本次转换响应中的HTTPS地址，不接受浏览器传入任意URL。
abort_unless(parse_url($url, PHP_URL_SCHEME) === 'https', 502, '结果地址无效');
$pdf = Http::timeout(60)->get($url)->throw()->body();
abort_unless(strncmp($pdf, '%PDF-', 5) === 0, 502, '结果不是PDF文件');

return response($pdf, 200, [
    'Content-Type' => 'application/pdf',
    'Content-Disposition' => 'attachment; filename="'.$filename.'"',
]);