設定 NextPDF Gotenberg

概覽

設定分散於兩個位置。第一個是不可變的 GotenbergConfig 值物件，用來描述服務與限制。第二個是 GotenbergBridge 建構子，負責接入 PSR HTTP 協作物件。兩者都採明確的建構子注入。套件內部沒有全域狀態、不讀取環境變數，也沒有隱藏的預設端點。

設定物件

GotenbergConfig 是一個 final readonly 值物件。你可以使用具名引數直接建構它，或透過 GotenbergConfig::fromArray() 從關聯陣列建立。

欄位

欄位	型別	預設值	效果
apiUrl	string	''	Gotenberg 服務的基底 URL。必填；空值會使設定無效，且每次轉換都會快速失敗。必須是 HTTPS。
timeout	int	30	硬性傳輸逾時，以秒為單位。使用選用的 cURL 釘選傳輸時，會由該傳輸套用。
maxFileSize	int	52_428_800	最大輸入大小，以位元組為單位（50 MiB）。超過此值的輸入會在發出任何請求前被拒絕。
apiKey	string	''	Bearer token。非空時會以 Authorization: Bearer <token> 標頭送出。標註為 #[\SensitiveParameter]，因此會在堆疊追蹤中被遮蔽。
pinnedPublicKeys	list<string>	[]	主要 TLS SPKI 釘選，格式為 sha256/<base64>。為空時停用釘選。
backupPublicKeys	list<string>	[]	備援 TLS SPKI 釘選；分開保存，以便個別驗證輪替。

直接建構

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    maxFileSize: 20 * 1024 * 1024,
    apiKey: $secretFromYourSecretStore,
);

從陣列建構

fromArray() 接受 snake_case 鍵，且會忽略任何格式不正確的內容，而不是拋出例外。非字串的 api_url 會變成 ''。非整數的 timeout 會回退為 30。非整數的 max_file_size 會回退為 50 MiB 預設值。非陣列的釘選清單會變成 []。釘選陣列中的非字串項目會被丟棄。

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

這種寬容解析是刻意設計的。它讓你能直接餵入框架設定陣列，無需額外的預先驗證層，同時仍產生型別正確的物件。它並不驗證 URL 是否可連線，也不驗證釘選是否正確。這些檢查會在轉換時執行。

有效性

isValid() 只有在 apiUrl 是非空字串時才回傳 true。它不執行網路或 scheme 檢查。HTTPS 與私有位址篩查會在轉換時由安全性原則執行。無效設定會導致 convertFile() 與 convertString() 拋出 GotenbergConvertException，訊息為 Invalid Gotenberg configuration: apiUrl is empty。無效設定也會使 isAvailable() 在不進行任何網路呼叫的情況下回傳 false。

橋接器建構子

GotenbergBridge 接收設定與 PSR 協作物件：

引數	型別	必填	效果
config	GotenbergConfig	是	上述服務描述子與限制。
httpClient	Psr\Http\Client\ClientInterface	是	供健康探測使用，並作為後備傳輸的 PSR-18 用戶端。
requestFactory	Psr\Http\Message\RequestFactoryInterface	是	建立 PSR-7 請求。
streamFactory	Psr\Http\Message\StreamFactoryInterface	是	建立請求主體串流。
logger	Psr\Log\LoggerInterface|null	否（預設 null）	提供時，每次轉換請求都會記錄一筆 debug 等級紀錄。
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	否	預設使用核心的預設 HTML 安全性原則。這是解析層原則，與傳輸層原則互補。
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	否（預設 null）	啟用 cURL 釘選傳輸時必須提供。未提供時，橋接器一律使用注入的 PSR-18 用戶端。

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    logger: $psrLogger,
    responseFactory: $psrResponseFactory,
);

傳輸選擇

橋接器有兩種傳輸，會針對每次轉換請求擇一使用：

• cURL 釘選傳輸 — 當注入了 responseFactory且有可釘選的目標（URL 解析出一個以上的 IP，或設定了 SPKI 釘選）時使用。此傳輸會以 CURLOPT_RESOLVE 綁定解析出的位址集合。有釘選存在時，會以 CURLOPT_PINNEDPUBLICKEY 強制執行 SPKI 釘選。它會驗證對端與主機（CURLOPT_SSL_VERIFYPEER、CURLOPT_SSL_VERIFYHOST = 2）。它會套用設定的逾時，並停用重新導向追蹤（CURLOPT_FOLLOWLOCATION = false、CURLOPT_MAXREDIRS = 0）。
• 注入的 PSR-18 用戶端 — 在所有其他情況下使用，包括 API URL 是裸的公開 IP 字面值（沒有 DNS 可釘選）且未設定 SPKI 釘選時，或未提供 responseFactory 時。

實務上的結果是：若要取得可抵抗 DNS 重新綁定的連線與 TLS 釘選，請注入 responseFactory 並設定釘選。無論選用哪種傳輸，健康探測一律使用注入的 PSR-18 用戶端。

TLS 公開金鑰釘選

釘選遵循 SHA-256 SPKI 指紋模型。每個釘選都是形如 sha256/<base64-encoded-spki-hash> 的字串。此傳輸也接受 cURL 原生的 sha256//<base64> 形式，並會把單斜線形式轉換成該形式。任何其他前綴都會引發 InvalidSpkiPinException。

allPublicKeyPins() 回傳 pinnedPublicKeys 與 backupPublicKeys 去重後的聯集。TLS 層會接受 SPKI 雜湊符合該合併集合中任一成員的憑證。在維運上，你至少應設定一個備援釘選，避免預定的憑證或金鑰輪替在新金鑰傳播期間將橋接器鎖在服務之外。將備援清單與主要清單分開保存，可讓你獨立於使用中的釘選來驗證並輪替備援釘選。輪替程序請參閱 /integrations/gotenberg/security-and-operations/。

每次請求的轉換選項

多部分酬載型別（GotenbergConvertPayload）除了檔案之外，還會攜帶兩個選用的 Gotenberg 轉換選項：

• landscape（bool，預設 false）— 透過 landscape 表單欄位送出，值為 "true" 或 "false"。
• nativePageRanges（string，預設 ''）— 僅在非空時透過 nativePageRanges 表單欄位送出；接受 Gotenberg 的範圍語法，例如 1-3 或 1,3,5-9。

公開的 convertFile() 與 convertString() 進入點會使用這兩個欄位的預設值建立酬載。這些欄位是酬載合約的一部分，並由測試套件驗證。若你需要橫向輸出或頁面選取，請從你自己的整合層公開它們。

另請參閱

• /integrations/gotenberg/install/ — 安裝與 Gotenberg 基準。
• /integrations/gotenberg/quickstart/ — 可執行的端到端範例。
• /integrations/gotenberg/production-usage/ — 設定來源、密鑰、逾時、重試。
• /integrations/gotenberg/security-and-operations/ — 完整的安全性模型與釘選輪替。
• /integrations/gotenberg/troubleshooting/ — 各個設定相關例外的意義。