NextPDF Gotenberg 的啟動與探索

概覽

此橋接器本身沒有自動探索機制。它是一個普通服務，你透過明確的建構子注入來建立它：一個組態值物件，加上 PSR HTTP 協作物件。此套件不隨附任何 service provider、bundle 或容器擴充功能，本身也不讀取任何環境變數。此處的「探索」是指主機框架如何提供協作物件；這是框架的工作，而非此套件的工作。

橋接器如何被探索

它不會被自動探索。你必須自行建構它。GotenbergBridge 需要四個引數，並接受三個選用引數：

必填：一個 GotenbergConfig、一個 PSR-18 用戶端、一個 PSR-17 請求工廠、一個 PSR-17 串流工廠。
選用：一個 PSR-3 記錄器、一個 HTML 安全政策（預設為 NextPDF 核心預設政策），以及一個 PSR-17 回應工廠。

回應工廠是 cURL 釘選傳輸的啟用開關。提供它後，只要有可供釘選的項目（已解析的位址或已設定的 SPKI 釘選），橋接器就會使用釘選傳輸。省略它時，則一律使用注入的 PSR-18 用戶端。完整的引數契約位於 /integrations/gotenberg/configuration/。

啟動序列

沒有註冊步驟。其生命週期如下：

主機解析一個 PSR-18 用戶端與多個 PSR-17 工廠。這件事由主機容器負責；套件並不負責。
應用程式從其組態來源建構一個 GotenbergConfig。GotenbergConfig::fromArray() 接受一個 snake_case 陣列，並透過套用預設值來容忍格式錯誤的值。請在你的啟動路徑中驗證此來源，讓缺少的 URL 在啟動時失敗，而不是每次轉換時才失敗。
應用程式使用該組態與協作物件來建構 GotenbergBridge。
第一次轉換呼叫會執行 URL 驗證、SSRF 與檔名篩查，然後送出該請求。建構時不會執行任何工作；在你呼叫橋接器之前，它會保持靜止。

容器繫結

此套件不隨附任何容器繫結。若要讓橋接器可被注入，請依下列方式在你的主機應用程式容器中註冊它：

從你的組態來源繫結 GotenbergConfig。
將 PSR-18 用戶端與 PSR-17 工廠繫結到你所選擇的實作。
將 GotenbergBridge 繫結為一個接收上述各項的服務。

框架原生的自動接線、組態發佈，以及 service-provider 或 bundle 註冊，皆位於專屬的框架整合套件中，不在此處。此套件刻意保持與框架無關。它僅相依於 PSR 介面，因此可在任何容器下運作。

組態解析順序

此套件本身不讀取任何組態。解析順序取決於你的應用程式在呼叫 GotenbergConfig::fromArray() 或建構子之前所實作的內容。常見順序是環境變數，接著是已發佈的組態檔，再來是程式碼預設值。該順序是你的應用程式契約，並非此套件的契約。此套件明確定義的是，傳入 fromArray() 的陣列在各欄位遺漏時使用的 預設值：空白的 API URL、30 秒逾時、50 MiB 大小上限、空白的 API 金鑰、空白的釘選清單。

診斷

有兩個內建訊號可確認接線狀況：

isAvailable() 會在不產生網路流量的情況下驗證 URL，接著向 <apiUrl>/health 送出一個 HEAD 請求，並在狀態低於 500 時回報為可用。任何失敗情況下，它都會回傳 false，而非拋出例外。請從就緒檢查中呼叫它。
對一份已知良好的小型文件進行冒煙轉換，可確認整條路徑端到端皆正常。這包括向 <apiUrl>/forms/libreoffice/convert 發出的 multipart 請求，以及回應驗證。

另請參閱

/integrations/gotenberg/integration/ — 透過此服務驅動 NextPDF 管線。
/integrations/gotenberg/install/ — 套件與服務安裝。
/integrations/gotenberg/configuration/ — 完整的建構子與組態契約。
/integrations/gotenberg/overview/ — 轉換流程與相依模型。