NextPDF Laravel 整合

概覽

本指南說明如何將 NextPDF 整合到 Laravel 12 應用程式。你會逐步完成六個階段：安裝套件、讓 Laravel 自動探索它、發布組態、resolve（解析）容器繫結、回傳一個 HTTP 回應，以及執行一個佇列工作。每個階段都會連到對應領域的深入參考文件。

安裝

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

啟動與自動探索

Laravel 會透過套件的 composer.jsonextra.laravel 區塊自動探索 service provider（服務提供者）與 facade 別名。你不需要編輯 config/app.php。autoload 對映只有一筆 PSR-4 項目。依據 PSR-4 前綴對應到基底目錄的規則（PSR-4 §3），NextPDF\Laravel\ 前綴會解析到 src/Laravel/。這個 provider 採延遲載入。只有在其中任一 provides() 項目第一次被解析時，才會啟動。完整的自動探索內部機制請見 /integrations/laravel/boot-and-discovery/。

容器繫結

從容器解析文件契約。已繫結的識別碼會解析到它所註冊的項目（PSR-11 §1.1.2）。文件以工廠（factory）方式繫結，所以每次解析都會給你一份全新的文件。字型與影像登錄表是單例（singleton），所以每次解析都會回傳同一個共用的實例。完整的繫結生命週期表請見 /integrations/laravel/overview/ 一節與 /integrations/laravel/boot-and-discovery/。

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Wired through the container', newLine: true);

發布組態

php artisan vendor:publish --tag=nextpdf-config

這個指令會寫出 config/nextpdf.php。每個鍵、對應的環境變數與預設值，都記載在 /integrations/laravel/configuration/。

Service provider 與套件冒煙測試

這個套件隨附一套以 Testbench 為基礎的測試，會完整驗證 provider。以下是一個你可以加進使用端應用程式的最小冒煙測試：

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

這兩個斷言對應到套件自身 EInvoiceServiceProviderIntegrationTest 中的單次使用一致性檢查。它們會確認文件是以工廠方式繫結，而字型登錄表是鎖定的單例。

公開 API 進入點

進入點	用途	參考文件
`NextPDF\Laravel\Facades\Pdf`	指向全新文件的靜態 proxy	/integrations/laravel/quickstart/（快速上手）
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	由容器解析出的文件	/integrations/laravel/production-usage/（正式環境用法）
`NextPDF\Laravel\Http\PdfResponse`	內嵌/下載/串流式 HTTP 回應	/integrations/laravel/security-and-operations/（安全性與維運）
`NextPDF\Laravel\Jobs\GeneratePdfJob`	以佇列方式產生	/integrations/laravel/production-usage/ 正式環境用法

程式碼範例 — 正式環境

透過依賴注入接線並完成錯誤處理的控制器，在 /integrations/laravel/production-usage/ 一節有完整說明。佇列工作及其成功與失敗回呼也在同一節說明。

邊界情況與陷阱

請解析 PdfDocumentInterface，而非具體的 Document。這能讓繫結保持可測試且可替換。
SignerInterface 與 TsaClient 在設定之前都會解析到 null。請務必做 null 檢查。
電子發票契約需要 nextpdf/premium。這些契約已經繫結，但缺少它時，第一次解析就會發生錯誤。

效能

由於 provider 採延遲載入，端到端接線不會增加啟動成本。第一次解析的建構成本與字型暖機成本，涵蓋在 /integrations/laravel/boot-and-discovery/ 一節。

安全性注意事項

PdfResponse 會套用固定的一組 OWASP 標頭。GeneratePdfJob 會在 worker 上驗證它的輸出路徑。威脅模型請見 /integrations/laravel/security-and-operations/ 一節。

一致性

聲稱	來源	條款	參考 ID
已繫結的識別碼會解析到它所註冊的項目	PSR-11 容器	§1.1.2
PSR-4 前綴對應到基底目錄	PSR-4 自動載入器	§3

商業情境

當安裝了 nextpdf/premium 時，簽章、PDF/A 與電子發票契約都會透過同一個 provider 整合。這是一項選用的 Enterprise 能力。這裡所記載的 Core 套件不需要任何程式碼變更即可採用它。請見 https://nextpdf.dev/get-license/?intent=laravel-signing。

另請參閱

/integrations/laravel/overview/ — 架構與繫結表
/integrations/laravel/install/ — 安裝與選用擴充功能
/integrations/laravel/quickstart/ — 第一個可執行的範例
/integrations/laravel/production-usage/ — 依賴注入、錯誤處理、佇列
/integrations/laravel/boot-and-discovery/ — 探索與生命週期