NextPDF Gotenberg 整合

概覽

本頁說明如何將橋接器連接到應用程式的其他部分。先安裝套件並完成接線，再把轉換後的 PDF 接入 NextPDF 後處理管線。橋接器負責將 Office 文件轉成 PDF，其餘處理則交由管線完成。本頁是 /integrations/gotenberg/boot-and-discovery/ 的任務導向配套文件；後者說明這種接線設計的原因。

安裝

composer require nextpdf/gotenberg

這會一併引入 nextpdf/core ^3.0 與 PSR HTTP 合約。請另外安裝 PSR-18 用戶端與 PSR-17 工廠，作為獨立套件。橋接器只依賴這些介面，因此實際使用的函式庫由你決定。完整安裝步驟，包含如何透過 HTTPS 架設 Gotenberg 服務，請參閱 /integrations/gotenberg/install/。

接線

以一個組態物件與 PSR 協作物件建構橋接器。同時注入一個回應工廠，這會啟用具備 DNS 釘選與 TLS 釘選的傳輸層：

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

橋接器要求設定的 URL 必須使用 HTTPS。它會在送出任何請求之前，拒絕純 http://。請在 TLS 終結層後方執行 Gotenberg，並讓橋接器指向該 HTTPS 端點。

容器繫結

在你的宿主容器中註冊三個項目。第一項是依你的組態來源建構的 GotenbergConfig。第二項是你的 PSR-18 用戶端，以及你的 PSR-17 工廠。第三項是由前述項目接線而成的 GotenbergBridge。本套件本身不提供任何繫結。框架原生註冊屬於專屬的框架整合套件。請參閱 /integrations/gotenberg/boot-and-discovery/。

組態

服務描述子及各項限制都由 GotenbergConfig 的欄位表示。這些欄位涵蓋 API URL、逾時時間、大小上限、bearer token，以及 TLS 釘選。每次請求的選項 landscape 與 nativePageRanges 則改放在負載型別的欄位中。/integrations/gotenberg/configuration/ 記載每個欄位，包含其型別、預設值與作用。

將轉換後的 PDF 接入 NextPDF 管線

典型的端到端流程如下：

以 convertFile() 或 convertString() 轉換 Office 文件。
取出 $result->pdfData，其中存放原始 PDF 位元組，並將其載入一份 NextPDF 文件。
套用後處理，例如頁面組裝、浮水印、PDF/A 轉換或數位簽章。

步驟 3 是 NextPDF 的職責，而不是橋接器的職責。nextpdf/premium 套件提供簽署、PDF/A 設定檔與浮水印。請將轉換與後處理維持為彼此獨立的階段。如此一來，你就能分別診斷每一項失敗。

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

Pro 版的 PAdES 支援僅限 B-B 基準層級。它並不提供 B-T、B-LT 或 B-LTA。透過此橋接器轉換文件，並不代表具備任何時間戳記或長期驗證能力。

冒煙測試

完成接線後，確認此整合可正常運作。你不需要轉換一份真實文件就能做到這件事：

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

isAvailable() 會先驗證 URL，這一步不產生任何網路流量。接著它會送出一個 HEAD 到 <apiUrl>/health。之後，再轉換一份已知正常的小型文件。這會走完整個通往 <apiUrl>/forms/libreoffice/convert 的 multipart 路徑與回應驗證。

公開 API 進入點

此整合所使用的公開介面：

GotenbergConfig — 不可變的服務描述子與各項限制；fromArray() 會依據組態陣列建構它。
GotenbergBridge::convertFile(string $path) — 轉換磁碟上的一個檔案。
GotenbergBridge::convertString(string $bytes, string $fileName) — 轉換存放於記憶體中的位元組。
GotenbergBridge::isAvailable() — 不擲出例外的就緒度探測。
GotenbergConvertResult — 包含 pdfData、sourceFormat、isValid() 與 size()。
GotenbergConvertException — 轉換層的例外型別。

完整合約位於 /integrations/gotenberg/configuration/ 與 /integrations/gotenberg/troubleshooting/。其中涵蓋傳輸層選擇與例外清單。

另請參閱

/integrations/gotenberg/boot-and-discovery/ — 接線設計的原因。
/integrations/gotenberg/quickstart/ — 一次有導引的初次轉換。
/integrations/gotenberg/production-usage/ — 機密、重試、逾時、可觀測性。
/integrations/gotenberg/install/ — 套件與 Gotenberg 服務安裝。