NextPDF Symfony 整合總覽
重點速覽
標題為「重點速覽」的區段nextpdf/symfony 是 NextPDF 引擎官方的 Symfony 7 bundle。它會將引擎接入 Symfony container（容器），並提供可注入到你自有服務的文件 factory（工廠）。它也內建 HTTP response 輔助工具，以及非同步產生 PDF 的路徑，讓這項工作可在背景執行。
bundle 提供哪些東西
標題為「bundle 提供哪些東西」的區段NextPDF Symfony 以標準 bundle 形式，將 nextpdf/core 引擎綁定到 Symfony 應用程式。它加入下列建構區塊；每一項都已對照 src/Symfony/ 中的 bundle 原始碼逐一驗證：
- 一個 bundle 進入點 —
NextPDF\Symfony\NextPdfBundle繼承 Symfony 的Bundle基底類別，並註冊一個 compiler pass。 - 一個依賴注入 extension —
NextPDF\Symfony\DependencyInjection\NextPdfExtension載入服務定義，將 config tree（組態樹）轉為 container 參數，並對外公開組態別名nextpdf。 - 一棵具型別的組態樹 —
NextPDF\Symfony\DependencyInjection\Configuration定義了nextpdf的組態 schema。這個 schema 會驗證 enum 值、設定預設值，並使用%kernel.*%參數 placeholder（佔位符）。 - 一個可注入的文件 factory —
NextPDF\Symfony\Service\PdfFactory會產生全新且預先設定好的NextPDF\Core\Document實例。它相當於 Symfony 版的靜態 facade。 - HTTP response 輔助工具 —
NextPDF\Symfony\Http\PdfResponse會建立 inline、下載與串流回應，並附上一組固定且符合 OWASP 原則的安全標頭。 - 一條非同步產生路徑 —
NextPDF\Symfony\Message\GeneratePdfMessage、NextPDF\Symfony\Message\GeneratePdfHandler與NextPDF\Symfony\Message\PdfBuilderInterface會與 Symfony Messenger 整合，讓 PDF 算繪可在 worker 上執行。 - 一個編譯期 extension 偵測器 —
NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass會偵測選用的 NextPDF extension，只有在這些 extension 存在時才註冊它們的服務。
容器契約
標題為「容器契約」的區段這個 bundle 會註冊一組規模小且穩定的公開 container 服務。文件服務 nextpdf.document（別名為 NextPDF\Contracts\PdfDocumentInterface 與 NextPDF\Core\Document）並非共享：每次 resolve（解析）都會回傳各自獨立、用完即丟的文件。這符合 PSR-11 容器契約：在該契約下，對相同識別碼連續呼叫兩次 get()，依容器設定不同，可能回傳不同的值 — 見 PSR-11 §1.1.2。非共享綁定是刻意設計：文件會累積每次算繪的狀態，因此每個請求都取得全新實例，可避免狀態在長時間執行的 worker 中跨請求外洩。
字型登錄（NextPDF\Contracts\FontRegistryInterface）的運作方式則相反：它是共享的 singleton（單例）。影像登錄帶有 kernel.reset 標籤，因此在 FrankenPHP 與 Messenger worker 下，其有界快取會在請求之間被清除。組態頁面記載了完整的服務與別名對照表。
選用的記錄功能
標題為「選用的記錄功能」的區段字型與影像登錄都接受選用的 PSR-3 logger。只有在應用程式提供 logger 時，這個 bundle 才會綁定 Psr\Log\LoggerInterface（nullOnInvalid()）。因此，記錄功能是選用的協作元件，而非硬性相依。這與 PSR-3 logger 契約一致：在該契約下，logger 是可注入、可替換的協作元件（PSR-3）。
核心能力與選用能力
標題為「核心能力與選用能力」的區段這個 bundle 本身是 Apache-2.0 核心軟體。少數能力只會在你同時安裝特定選用套件時出現：
| 能力 | 需要 | 偵測方式 |
|---|---|---|
PDF 產生、PdfFactory、PdfResponse | 僅需核心 | 永遠可用 |
| 非同步產生 | symfony/messenger | 安裝 Messenger 後 handler 即啟用 |
| Chrome CDP HTML 算繪 | nextpdf/artisan | 編譯期 class_exists 探測 |
| PDF/A 封存、數位簽章 | nextpdf/premium（安裝 Pro） | 編譯期 class_exists 探測 |
安裝 nextpdf/premium 後，這個 bundle 可套用一組基線 PAdES B-B 簽章設定。更高階的簽章設定檔不在這個 bundle 的文件範圍內。版本對照矩陣請參閱 NextPDF Premium 文件。
何時該使用這個 bundle
標題為「何時該使用這個 bundle」的區段當你要在 Symfony 7 HTTP 應用程式或 worker 內建構 PDF 時，就使用 nextpdf/symfony。這個 bundle 提供由 container 管理的服務、worker 安全的登錄，以及安全的下載回應，因此你不必手動接線引擎。如果你只需要在腳本中進行一次性產生，單靠核心套件 nextpdf/core 就足夠了。
符合性
標題為「符合性」的區段每一列都是本頁提出的一則規範性主張，並釘選到來自受管制 SDO 語料庫的完整 64 位十六進位 reference_id。Provenance（來源資訊；語料庫 manifest、檢索傳輸）記於 _sidecars/rag-citations.yaml。
| 規範 | 條款 | 參考 ID | 主張 |
|---|---|---|---|
| PSR-11 | psr_11_container#1.1.2.p3.b | Container get() 回傳值契約 | |
| PSR-3 | psr_3_logger#x3.p17 | LoggerInterface 選用相依 |
商業脈絡
標題為「商業脈絡」的區段當 nextpdf/premium（Pro）與這個 bundle 一同安裝時，數位簽章與 PDF/A 封存就會變為可用。這是一項選用的 Pro 能力。此處記載的 Core bundle 採用它時，不需要任何程式碼變更。見 </get-license/?intent=symfony-pro>。
另請參閱
標題為「另請參閱」的區段- /integrations/symfony/install/ — 安裝並註冊這個 bundle。
- /integrations/symfony/configuration/ — 完整的
nextpdf組態樹與服務對照表。 - /integrations/symfony/quickstart/ — 一個可執行的控制器與非同步範例。
- /integrations/symfony/boot-and-discovery/ — Symfony 如何探索並啟動這個 bundle。
- /integrations/symfony/production-usage/ — worker 安全性、串流與非同步模式。