Laravel API 參考

速覽

這個 nextpdf/laravel 套件會將與 Framework（框架）無關的 NextPDF 核心整合進 Laravel 應用程式。它提供四項可直接呼叫的 API：方便快速撰寫的 Pdf facade、用來透過注入建立文件的 PdfDocumentInterface 容器綁定、將完成文件轉為 HTTP 回應的 PdfResponse 輔助函式，以及用於在請求流程之外生成文件的 GeneratePdfJob 佇列任務。NextPdfServiceProvider 會註冊所有綁定並支援自動探索，因此不需要手動設定。config/nextpdf.php 中的組態會控制預設值、字型、佇列，以及選用的簽章與 TSA 功能。

從這裡開始：若要直接從控制器送出 PDF，先建立一份文件，再回傳 PdfResponse::download($document, 'file.pdf')；請參考下方第一個範例。

常見任務

下方的程式片段涵蓋你最先會用到的三種流程。每一個都已對照套件原始碼驗證；完整的逐符號表格接在後面。

從控制器回傳可下載的 PDF，是最常見的任務：

<?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(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

它的作用：注入一份全新文件、寫入一行，並回傳一個 attachment 回應，其中包含 Content-Type: application/pdf 與 OWASP 安全標頭。把 download() 換成 inline()，即可改為在瀏覽器中預覽。

用 Pdf facade 撰寫並儲存，是腳本與簡短流程中最短的路徑：

<?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'));

它的作用：facade 會從容器 resolve（解析）出一份全新文件、寫入一個 cell，然後將完成的 PDF 儲存到磁碟。

用 GeneratePdfJob 在請求執行緒之外生成 PDF：

<?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),
);

它的作用：把生成工作排入 worker 佇列。builder（建構器）閉包會收到一份由容器解析出的文件，並回傳該文件。任務會在儲存前驗證 .pdf 輸出路徑。佇列名稱、逾時與連線都來自 config('nextpdf.queue.*')。

Facade（外觀模式）

這個 Pdf facade 會以靜態方式委派給一份全新的核心 Document；適合用在靜態寫法讀起來較順的簡短控制器流程。每一列都是一個被委派的文件方法。

符號	參數	預設行為	回傳	拋出或失敗的情況	備註
`NextPDF\Laravel\Facades\Pdf`	無；靜態 facade 存取器會解析出 `NextPDF\Contracts\PdfDocumentInterface`	Laravel 會為文件介面解析出目前的容器綁定。	底層核心文件的流暢式 API。	若未註冊 provider，Laravel 容器綁定會失敗。	用於簡短的控制器流程。服務與任務建議改用建構子注入。
`Pdf::setTitle(string $title)`	`title`：文件標題。	會取代任何既有標題。	`static`	核心驗證或寫入時的錯誤。	委派到核心 `Document`。
`Pdf::setAuthor(string $author)`	`author`：文件作者中繼資料。	會取代任何既有作者。	`static`	核心中繼資料驗證錯誤。	套用全應用程式範圍的中繼資料時，建議優先使用設定好的預設值。
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`：選用的頁面尺寸；`orientation`：預設為 `Portrait`。	省略 `size` 時，會採用 configured/default 頁面尺寸。	`static`	核心頁面驗證錯誤。	當輸出尺寸很重要時，請明確指定 `PageSize`。
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	字型家族、樣式與點數大小。	空白樣式與 12 pt 大小。	`static`	字型登錄或編碼錯誤。	當延遲很重要時，請透過 `nextpdf.preload_fonts` 預先載入正式環境字型。
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	cell 方塊、文字、邊框旗標、換行旗標、對齊方式。	空白文字、無邊框、不換行、靠左對齊。	`static`	版面配置或文字編碼錯誤。	用於簡單的固定版面配置輸出。
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	cell 寬度、行高、文字、邊框旗標、對齊方式。	無邊框且靠左對齊。	`static`	版面配置或文字編碼錯誤。	當文字需要在固定寬度內換行時使用。
`Pdf::writeHtml(string $html)`	`html`：HTML 片段。	會繪製到目前頁面，必要時自動建立一頁。	`static`	核心 HTML 繪製錯誤。	在接受不受信任的 HTML 之前，先套用輸入大小與資源政策。
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	檔案路徑與選用的擺放矩形。	省略座標時，會讓核心文件自行選擇目前位置與固有尺寸。	`static`	影像解碼、路徑或版面配置錯誤。	在接受使用者提供的路徑之前，先驗證影像來源政策。
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`：選用的名稱；`dest`：輸出目的地。	省略目的地時，會採用 inline 輸出。	`string`	核心序列化錯誤。	在 Laravel HTTP 回應中，建議優先使用 `PdfResponse`。
`Pdf::save(string $path)`	`path`：檔案系統目標。	把完成的 PDF 寫入磁碟。	`void`	檔案系統或核心寫入錯誤。	在應用程式程式碼中驗證輸出目錄。
`Pdf::getPdfData()`	無。	把 PDF 具現化到記憶體中。	`string`	核心序列化錯誤。	當回應主體必須由另一個框架物件擁有時使用。

Service provider 與綁定

當你需要直接解析或覆寫某個容器項目時，請查閱這張表；例如把 DocumentFactoryInterface 注入某個服務，或確認 provides() 延後載入了哪些項目。

符號	參數	預設行為	回傳	拋出或失敗的情況	備註
`NextPdfServiceProvider::register()`	無。	會合併 `config/nextpdf.php`，並註冊各項登錄、文件工廠、文件綁定、HTTP 用戶端、TSA 用戶端、簽章器，以及選用的電子發票合約。	`void`	使用某項功能時，可能出現容器或選用類別解析錯誤。	`FontRegistryInterface` 與 `ImageRegistry` 為共用；文件則永遠是全新的。
`NextPdfServiceProvider::boot()`	無。	會驗證必要的 PHP 擴充功能，並在 console 模式下發布 `nextpdf-config`。	`void`	`RuntimeException`：當必要的擴充功能無法使用時拋出。	必要的擴充功能為 `mbstring` 與 `zlib`。
`NextPdfServiceProvider::provides()`	無。	回報延後載入的服務 ID。	`array<string>`	預期不會發生。	包含 `PdfDocumentInterface`、`DocumentFactoryInterface`、`FontRegistryInterface`、`SignerInterface`、`TsaClient`、`ClientInterface`，以及 `nextpdf`。
`PdfDocumentInterface` / `nextpdf`	從 Laravel 容器解析。	會建立一份一次性的 `Document`（取自 `DocumentFactoryInterface`），接著套用設定好的預設值與選用的 PDF/A 或 Artisan 設定。	`NextPDF\Core\Document`	在已設定但無法使用時，可能出現選用擴充功能的錯誤。	為每個請求或任務解析出一份新文件。
`DocumentFactoryInterface`	從 Laravel 容器解析。	在整個行程生命週期內共用字型與影像登錄的單例工廠。	`DocumentFactoryInterface`	登錄設定錯誤。	用於明確的相依性注入。
`SignerInterface`	從 Laravel 容器解析。	除非已設定 `nextpdf.signature.enabled` 與憑證路徑，否則會回傳 `null`。	`SignerInterface	null`	憑證載入或簽章層級的驗證錯誤。

組態

用這張表查閱各綁定會讀取的執行階段層面 nextpdf.* 鍵；完整的逐鍵參考，連同環境變數與預設值，請見 /integrations/laravel/configuration/ 一節。

鍵	型別	預設行為	備註
`nextpdf.fonts_path`	`string`	省略時會使用 Laravel 資源字型。	自訂字型與暖機用的目錄。
`nextpdf.cache_path`	`string`	應用程式快取路徑。	保持讓 PHP worker 可寫入。
`nextpdf.preload_fonts`	`list<string>`	空清單。	會在建立登錄時暖機，之後該登錄即被鎖定。
`nextpdf.image_cache_mb`	`int`	有上限的影像快取大小。	限制行程生命週期內的影像快取記憶體。
`nextpdf.defaults.*`	`array`	建立者 `NextPDF`、語言 `en`，以及選用的作者與版面配置預設值。	套用到每一份全新文件。
`nextpdf.artisan.*`	`array`	除非已安裝並設定，否則會停用 Chrome renderer（渲染器）。	對映到 `ChromeRendererConfig::fromArray()`。
`nextpdf.signature.*`	`array`	簽章預設為停用。	憑證、私鑰、密碼、額外憑證與簽章層級。
`nextpdf.tsa.*`	`array`	當 URL 為空時，TSA 為停用。	支援憑證、mTLS 檔案、逾時、公鑰釘選，以及 HTTP 政策。
`nextpdf.ocsp_cache.*`	`array`	OCSP 快取啟用，並使用設定好的 TTL。	可用時供簽章驗證流程使用。

HTTP 回應

當你要透過 HTTP 回傳一份完成的文件，並需要在 inline 顯示、attachment 下載或串流輸出之間選擇時，請使用這張表。

符號	參數	預設行為	回傳	拋出或失敗的情況	備註
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`：已建立的文件；`filename`：Content-Disposition 檔名。	空檔名會正規化為 `document.pdf`。	`Illuminate\Http\Response`	核心序列化或回應建構錯誤。	設定 PDF 內容型別與防禦性標頭。
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	與 `inline` 相同；disposition 為 attachment。	瀏覽器會下載回應。	`Illuminate\Http\Response`	與 `inline` 相同。	用於明確的檔案下載。
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	與 `inline` 相同。	把 PDF 位元組具現化，接著以 64 KB 區塊送出。	`Symfony\Component\HttpFoundation\StreamedResponse`	與 `inline` 相同。	這是串流 HTTP 輸出，並非零複製繪製。
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	與 `streamInline` 相同；disposition 為 attachment。	以下載方式串流回應。	`StreamedResponse`	與 `streamInline` 相同。	在繪製之前，強制執行輸入與輸出大小限制。

佇列任務

當你把生成工作移出請求執行緒時，請使用這張表；它涵蓋 GeneratePdfJob 的建構、派發，以及成功或失敗回呼的附加方式。

符號	參數	預設行為	回傳	拋出或失敗的情況	備註
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`：目標 `.pdf`；`builder`：會收到一個 `PdfDocumentInterface`；回呼為選用。	佇列名稱、逾時與連線都會從 `config('nextpdf.queue.*')` 讀取。	任務實例。	若 builder 或回呼無法序列化，會發生序列化錯誤。	builder 必須回傳設定好的文件。
`GeneratePdfJob::handle()`	無。	會解析出 `PdfDocumentInterface`、套用 builder、驗證輸出路徑，然後儲存。	`void`	`InvalidArgumentException`：對不安全的輸出路徑拋出；以及核心寫入錯誤。	會拒絕串流包裝器、null 位元組、`..` 區段，以及非 `.pdf` 的路徑。
`GeneratePdfJob::failed(Throwable $exception)`	`exception`：失敗原因。	若已設定失敗回呼，會呼叫它。	`void`	回呼失敗。	讓回呼保持冪等。
`GeneratePdfJob::then(callable $callback)`	`callback`：會收到輸出路徑。	會取代成功回呼。	`self`	可序列化閉包的錯誤。	用於派發設定的流暢式輔助方法。
`GeneratePdfJob::catch(callable $callback)`	`callback`：會收到拋出的 `Throwable`。	會取代失敗回呼。	`self`	可序列化閉包的錯誤。	用於警報或補償性清理。

開發備註

PdfResponse 一律會在建構回應前呼叫 getPdfData()。它不是延遲式文件建構器。
在共用傳輸環境中，佇列酬載可能遭竄改；請將輸出路徑限制在應用程式自有目錄內。
每個請求或任務都會使用一份全新文件。不要跨請求重複使用同一份文件。