NextPDF Symfony 整合

概覽

安裝 nextpdf/symfony，讓 Flex 註冊這個套件（bundle）（或由你手動註冊），加入 config/packages/nextpdf.yaml，再注入 PdfFactory。本頁是整個接線流程的 Index（索引）。每個步驟都會連到更深入的頁面。

安裝

composer require nextpdf/symfony

這個套件需要 nextpdf/core^3.0 || ^5.2、symfony/*^7.2，以及 psr/log^3.0。類別會以 PSR-4 前綴 NextPDF\Symfony\ 自動載入，並對映到 src/Symfony/。PSR-4 自動載入器會把命名空間前綴 resolve（解析）到該基底目錄（PSR-4 §2）。完整需求與選用套件，請見 /integrations/symfony/install/.

開機與自動探索

使用 Symfony Flex 時，套件位於 composer.json 中的 extra.symfony.bundles 項目會在所有環境中註冊 NextPDF\Symfony\NextPdfBundle。如果沒有使用 Flex，就自行把它加入 config/bundles.php：

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

完整的開機順序與 compiler pass 行為，請見 /integrations/symfony/boot-and-discovery/.

容器繫結

套件的 config/services.php 檔案會註冊以下服務：

服務 / 別名	生命週期
`NextPDF\Symfony\Service\PdfFactory`	共用、public——注入這個
`nextpdf.document` → `PdfDocumentInterface` → `Document`	非共用、public——每次解析都產生新的
`NextPDF\Contracts\FontRegistryInterface`	共用、暖機後鎖定
`NextPDF\Graphics\ImageRegistry`	共用、`kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	共用
`NextPDF\Symfony\Http\PdfResponse`	public、無狀態的輔助類別

document 繫結刻意設為非共用。PSR-11 允許容器對同一個 id 連續呼叫 get() 時回傳不同的值。每次都產生全新的 document，可以避免在長時間執行的 worker 中帶入跨請求狀態（PSR-11 §1.1.2）。完整的服務與別名表，包含條件式的 EInvoice 繫結，請見 /integrations/symfony/configuration/.

發布組態

組態別名是 nextpdf。請建立 config/packages/nextpdf.yaml。Flex recipe 發布後，會替你放入一份預設副本。每個鍵都有預設值，因此最精簡的檔案如下：

nextpdf: ~

完整的組態樹記載於 /integrations/symfony/configuration/.

初次使用

注入 PdfFactory，再透過 PdfResponse 回傳結果：

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class PdfController
{
    #[Route('/hello.pdf', name: 'hello_pdf')]
    public function hello(PdfFactory $pdf): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->cell(0, 10, 'Hello from NextPDF on Symfony.');

        return PdfResponse::inline($doc, 'hello.pdf');
    }
}

端對端的控制器與 Messenger 非同步路徑，請見 /integrations/symfony/quickstart/.

套件煙霧測試

不用撰寫任何應用程式碼，也能確認接線是否正確：

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console lint:container

debug:container nextpdf 應會列出 PdfFactory、nextpdf.document 別名，以及各個 registry。lint:container 會驗證每個服務引數都能解析。若要測試產生功能，請加入上方的控制器，然後請求 /hello.pdf。

公開 API 進入點

以下是應用程式碼可支援使用的公開符號：

符號	用途
`NextPDF\Symfony\Service\PdfFactory::create()`	全新、已預先設定的 `Document`
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	帶有安全標頭的緩衝回應
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	分塊串流（stream）回應
`NextPDF\Symfony\Message\GeneratePdfMessage`	非同步產生用的 DTO（已驗證）
`NextPDF\Symfony\Message\PdfBuilderInterface`	由 handler 解析的 builder 契約

符合性

每一列都是本頁提出的一項規範性主張。每項主張都釘定到一個來自受管控 SDO 語料庫的完整 64 位十六進位 reference_id。provenance（來源資訊）（語料庫資訊清單、檢索傳輸）放在 _sidecars/rag-citations.yaml。

規範	條款	參考 ID	主張
PSR-11	`psr_11_container#1.1.2.p4`		容器的 has() / get() 識別碼契約
PSR-4	`psr_4_autoload#x1.x2.p5`		自動載入器命名空間對映

另見

/integrations/symfony/install/ — 需求與註冊。
/integrations/symfony/boot-and-discovery/ — 探索、開機、compiler pass。
/integrations/symfony/configuration/ — 完整綱要與服務表。
/integrations/symfony/quickstart/ — 可執行的控制器與非同步範例。
/integrations/symfony/production-usage/ — worker 安全性與串流。