安裝 NextPDF Symfony 套件

概覽

使用 Composer 安裝套件。在啟用 Symfony Flex 的應用程式中，套件會自行註冊。若應用程式未使用 Flex，你只要在 config/bundles.php 註冊一次即可。

需求條件

以下限制條件取自套件的 composer.json。

相依套件	限制條件
`php`	`>=8.4 <9.0`
`nextpdf/core`	`^3.0 \|\| ^5.2`
`symfony/framework-bundle`	`^7.2`
`symfony/dependency-injection`	`^7.2`
`symfony/config`	`^7.2`
`symfony/http-foundation`	`^7.2`
`psr/log`	`^3.0`

套件也會在容器建構時額外檢查兩個 PHP 擴充功能：ext-mbstring 與 ext-zlib。這兩者在每個受支援的 PHP 執行階段都已啟用。若缺少其中任一個，這道檢查會以清楚的訊息快速失敗。

選用套件

以下套件宣告在套件 composer.json 的 suggest 底下。當它們存在於專案中時，會啟用額外行為：

套件	新增功能
`nextpdf/artisan`	Chrome CDP 的 HTML 渲染，在編譯期自動偵測
`nextpdf/premium`	PDF/A 封存與數位簽章（會安裝 Pro 等級），在編譯期自動偵測
`symfony/messenger`	透過 Messenger handler 非同步產生 PDF

用 Composer 安裝

composer require nextpdf/symfony

套件會透過 PSR-4 前綴 NextPDF\Symfony\ 自動載入，並對映到 src/Symfony/。這項對映宣告在 composer.jsonautoload.psr-4。Composer 產生的自動載入器會依照 PSR-4 自動載入規範，將命名空間前綴對映到該基底目錄 —— 詳見 PSR-4 §2。

註冊套件

Symfony Flex（建議）

套件在 composer.json 內附帶一個自動註冊提示：

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

在啟用 Flex 的應用程式中，這筆項目會將套件加入 config/bundles.php，並套用到每個環境（all）。你不需要手動編輯這個檔案。關於這套註冊模型，請參閱 Symfony 官方套件文件 (https://symfony.com/doc/current/bundles.html)。

手動註冊（不使用 Flex）

若應用程式未使用 Symfony Flex，請自行將套件加入 config/bundles.php：

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

套件類別是 NextPDF\Symfony\NextPdfBundle。它繼承 Symfony 的 Symfony\Component\HttpKernel\Bundle\Bundle 基底類別。套件的 getPath() 會回傳套件根目錄；build() 方法會註冊 OptionalExtensionPass 編譯器 pass。

提供組態檔

套件的組態別名是 nextpdf。請建立 config/packages/nextpdf.yaml。發布後，Flex recipe 會在這裡替你放一份預設副本。如果完全倚賴內建預設值，最小檔案會像這樣：

nextpdf: ~

每個鍵都有預設值，因此空組態也有效。完整的組態樹記載於 /integrations/symfony/configuration/ 一節。

驗證安裝

確認容器看得到套件服務：

php bin/console debug:container nextpdf

你應該會看到包含 nextpdf.document 別名與 NextPDF\Symfony\Service\PdfFactory 的服務。若要檢視解析（resolve）後的組態，請執行：

php bin/console debug:config nextpdf

這會印出合併後的組態樹，也就是你的覆寫值與預設值合併後的結果。

邊際情況與陷阱

Core 限制條件範圍 —— 套件接受 nextpdf/core^3.0 || ^5.2。 Composer 會解析出能滿足你其餘相依關係圖的那一個。如果你需要明確的引擎版本，請在應用程式的 composer.json 裡釘住單一主版本。
缺漏擴充功能的把關 —— 如果 php bin/console 在啟動時失敗，並出現關於 ext-mbstring 或 ext-zlib 的訊息，請在 php.ini 裡啟用該擴充功能。這是刻意設計的快速失敗行為，並非套件缺陷。
Flex 未註冊套件 —— 清除 Composer 快取後重新安裝。如果你不使用 Flex，請回到手動的 config/bundles.php 步驟。

符合性

每一列都代表本頁提出的規範性主張，並錨定到受管 SDO 語料庫提供的一組完整 64 位十六進位 reference_id。來源（Provenance）資訊放在 _sidecars/rag-citations.yaml，涵蓋語料庫資訊清單與檢索傳輸。

規格	條款	參考 ID（reference_id）	主張
PSR-4	`psr_4_autoload#x1.x2.p5`		自動載入器會將命名空間前綴對映到目錄

另請參閱

/integrations/symfony/overview/ —— 套件提供的功能。
/integrations/symfony/configuration/ —— 完整的組態樹與服務表。
/integrations/symfony/quickstart/ —— 第一個可執行的控制器。
/integrations/symfony/boot-and-discovery/ —— 探索與啟動順序的深入說明。