NextPDF Laravel 快速入門

概覽

在本教學中，你會透過一個控制器產生可下載的 PDF。接著，你會把同一項工作移到佇列任務執行。每段程式碼片段都對應一項由套件測試套件驗證的行為。

安裝

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

概念總覽

三個進入點幾乎涵蓋所有 Laravel 使用情境。facade（外觀）讓你以最快的方式上手。PdfResponse 會把文件轉成 HTTP 回應。佇列任務會把繁重的產生工作移出請求執行緒，讓使用者不必等待。本教學會依序說明這三種方式。加入錯誤處理的正式環境版本請見 /integrations/laravel/production-usage/。

程式碼範例 —— 快速入門

1. Facade（外觀）

facade 每次呼叫時，都會從容器 resolve（解析）出一份全新的文件。容器是 Laravel 的服務註冊表。這段程式碼片段對應 tests/Unit/Laravel/Facades/PdfTest.php 所驗證的行為。

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

2. 從控制器回傳下載回應

PdfResponse::download() 會回傳一個 Illuminate\Http\Response，並帶有 Content-Type: application/pdf、attachment 處置方式，以及 OWASP 安全標頭。tests/Unit/Laravel/Http/PdfResponseTest.php 會檢查狀態碼、內容類型、處置方式前綴與標頭。

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

若要在瀏覽器中內嵌預覽，將 download() 換成 inline() 即可。對於大型文件，請改用 streamInline() 或 streamDownload()。這兩個方法會以確定性的 64 KB 區塊傳送 PDF。

3. 佇列產生

GeneratePdfJob 會在佇列 worker 上建構並儲存一份 PDF。建構器 closure 會接收由容器解析出的文件，並回傳設定完成的文件。tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php 會確認任務會在指定的輸出路徑建立該檔案。

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

輸出路徑必須以 .pdf 結尾。任務會在 worker 上寫入前先驗證該路徑。

程式碼範例 —— 正式環境

正式環境版本加入明確的錯誤處理、任務上的成功與失敗回呼，以及具型別的例外處理策略。完整說明文件位於 /integrations/laravel/production-usage/。

邊界情況與陷阱

facade 每次解析都會回傳不同的文件實例。請勿跨多份邏輯文件快取 Pdf::getFacadeRoot()。
傳給任何 PdfResponse 工廠的空檔名，會預設為 document.pdf。回應測試套件會驗證這項預設值。
非 ASCII 檔名會自動取得一個 RFC 5987 filename*= 參數；ASCII 檔名則不會。
GeneratePdfJob 會拒絕路徑遍歷、stream 包裝器、null 位元組，以及任何非 .pdf 的副檔名。它會在 worker 上拋出 InvalidArgumentException。

效能

單頁文件的產生時間，遠在 front-matter 所定義的每頁牆鐘時間預算之內。把產生工作移到 GeneratePdfJob，可將 PDF 建構時間完全從 HTTP 請求中移除。請求會在任務派送後立即返回。

安全性須知

PdfResponse 工廠會套用一組固定的 OWASP 標頭。它們也會清理下載檔名。佇列任務會驗證它的輸出路徑。詳盡的威脅涵蓋說明位於 /integrations/laravel/security-and-operations/。

一致性

沒有任何規範性標準適用於這份教學。每段程式碼片段都已對照套件原始碼驗證，也已對照 tests/ 之下對應的測試驗證。

商業情境

簽章與 PDF/A 輸出可透過 nextpdf/premium 取得。這是一項選用的 Enterprise 功能。此處所述的 Core 套件無需更動任何程式碼即可採用它。請參閱 https://nextpdf.dev/get-license/?intent=laravel-signing。

另請參閱

/integrations/laravel/install/ —— 安裝並發布 config
/integrations/laravel/production-usage/ —— 使用 DI 注入、具錯誤處理的控制器與任務
/integrations/laravel/configuration/ —— 本頁用到的 config 鍵
/integrations/laravel/overview/ —— 架構與繫結生命週期