跳到內容
NextPDF

NextPDF Symfony 啟動與探索機制

概覽

標題為「概覽」的區段

核心（kernel）會註冊 NextPdfBundle。套件的 DI 擴充會載入 services.php，並將組態樹（config tree）解析（resolve）為容器參數。接著，單一編譯器階段（compiler pass）會接線選用擴充與字型預熱（font warmup）。

Symfony Flex 如何辨識此套件

標題為「Symfony Flex 如何辨識此套件」的區段

套件的 composer.json 宣告了自動註冊提示：

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

在 Symfony Flex 應用程式中，這會將 NextPDF\Symfony\NextPdfBundle 加入 config/bundles.php，並套用至每個環境（all）。若未使用 Flex，請在 config/bundles.php 中手動加入此套件。Symfony 官方文件正式說明了套件註冊模型（https://symfony.com/doc/current/bundles.html）。套件的類別會依 PSR-4 前綴 NextPDF\Symfony\ 自動載入，並對映至 src/Symfony/。PSR-4 自動載入器會將命名空間前綴對映至該基底目錄（PSR-4 §2）。

啟動順序

標題為「啟動順序」的區段

以下啟動順序已依套件原始碼驗證：

  1. 核心註冊套件。 Kernel::registerBundles() 會讀取 config/bundles.php 並建立 NextPDF\Symfony\NextPdfBundle 的實例，該類別繼承自 Symfony\Component\HttpKernel\Bundle\Bundle。
  2. 套件建構。 NextPdfBundle::build() 會呼叫父類別，接著註冊單一編譯器階段：OptionalExtensionPass。NextPdfBundle::getPath() 會回傳套件根目錄。
  3. 擴充載入。 DI 擴充 NextPDF\Symfony\DependencyInjection\NextPdfExtension（別名 nextpdf）會執行 processConfiguration()，並依 Configuration 處理組態。它會把解析後的值設為 nextpdf.* 容器參數，接著透過 PhpFileLoader 載入 config/services.php。
  4. 必要擴充防護。 NextPdfExtension::load() 在結尾會斷言 ext-mbstring 與 ext-zlib 皆存在，否則提早失敗。
  5. 編譯器階段執行。 在容器編譯期間，OptionalExtensionPass::process() 會在 PdfFactory 上設定擴充可用性旗標，視情況註冊簽署器與 TSA 用戶端，並排程字型登錄的預熱與鎖定。
  6. 容器編譯並快取。 Symfony 會寫出編譯後的容器。cache:warmup 會在流量進來前先執行此步驟。

編譯器階段

標題為「編譯器階段」的區段

此套件只註冊一個階段 NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass，並在 NextPdfBundle::build() 中加入。它在預設（最佳化前）的階段群組中執行。此階段會執行四個步驟。每個步驟都有條件防護；輸入不存在時不會產生作用：

  • 擴充旗標 — 在 PdfFactory 定義中加入 setArtisanAvailable(...) 與 setProAvailable(...) 方法呼叫。這些值來自編譯期對 Artisan 瀏覽器工廠（factory）與 Pro PDF/A 類別執行的 class_exists 探測。
  • 簽署器註冊 — 當 nextpdf.signature 存在、enabled 為 true 且已設定憑證時，會為基準 B-B 設定檔註冊憑證資訊工廠與簽署器服務。
  • TSA 用戶端 — 當 nextpdf.tsa 設定 URL 時，會註冊一個 TSA 用戶端服務。
  • 字型預熱 — 當 nextpdf.preload_fonts 非空時，會在字型登錄定義中加入 warmup() 與 lock() 方法呼叫。

容器繫結

標題為「容器繫結」的區段

config/services.php 定義了這些服務。文件服務 nextpdf.document（別名為 NextPDF\Contracts\PdfDocumentInterface 與 NextPDF\Core\Document）是 非共用 的：每次解析都會回傳一份全新文件，這是 PSR-11 明確允許的；對同一個 id 連續呼叫 get()，可能回傳不同的值（PSR-11 §1.1.2）。字型登錄是共用的，並在預熱後鎖定。影像登錄是共用的，並標記為 kernel.reset。完整表格請見 /integrations/symfony/configuration/。

組態解析順序

標題為「組態解析順序」的區段
  1. 來自 Configuration 的內建預設值（getConfigTreeBuilder()）。
  2. config/packages/nextpdf.yaml 中的應用程式覆寫，以及 config/packages/<env>/ 下的環境覆寫。
  3. Symfony 會解析 %kernel.*% 參數 placeholder（佔位符）。舉例來說，fonts_path 預設為 %kernel.project_dir%/resources/fonts。
  4. NextPdfExtension::load() 會將合併後的結果寫入 nextpdf.* 容器參數，供 services.php 與編譯器階段使用。

無效值會在步驟 1–2 觸發 Symfony InvalidConfigurationException 而失敗。

診斷

標題為「診斷」的區段
Terminal window
php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

第一個指令會列出已註冊的服務。第二個指令會印出合併後的組態。第三個指令會重建容器，並重新執行編譯期的擴充探測。

符合性

標題為「符合性」的區段

每一列都是本頁面提出的規範性主張，並釘選到來自受管 SDO 語料庫的完整 64 位十六進位 reference_id。Provenance（來源資訊，含語料庫資訊清單與檢索傳輸）存放於 _sidecars/rag-citations.yaml。

規範條款參考 ID（reference_id）主張
PSR-11psr_11_container#1.1.2.p3.b容器解析可能每次呼叫都不同
PSR-4psr_4_autoload#x1.x2.p5命名空間前綴對映到基底目錄

另請參閱

標題為「另請參閱」的區段
  • /integrations/symfony/integration/ — 端對端接線參考。
  • /integrations/symfony/install/ — 安裝與註冊。
  • /integrations/symfony/configuration/ — 完整組態樹與服務表。
  • /integrations/symfony/overview/ — 功能摘要。