安裝 NextPDF Gotenberg

概覽

安裝橋接分為兩個部分。第一個部分是 PHP 套件及其 PSR HTTP 相依套件，透過 Composer 安裝。第二個部分是該套件會呼叫的 Gotenberg 服務。橋接會將工作交給該服務執行轉換，因此在 Gotenberg 執行個體可連線之前，它無法轉換任何內容。

在你撰寫任何轉換程式碼之前，請先完成這兩個部分。

需求

需求	限制	原因
PHP	>=8.4 <9.0	套件在 composer.json 中宣告此範圍。
NextPDF 核心	^3.0	在 composer.json 中宣告的直接相依套件。
PSR-18 HTTP 用戶端	^1.0	橋接透過注入的 Psr\Http\Client\ClientInterface 送出請求。
PSR-17 HTTP 工廠	^1.1	橋接透過注入的 PSR-17 工廠來建構請求與串流。
PSR-3 記錄器	^3.0（選用）	可注入記錄器以進行請求層級的偵錯記錄。
Gotenberg 服務	可透過 HTTPS 連線	轉換是由外部服務執行，而非由此套件執行。

橋接並未內建 PSR-18 用戶端或 PSR-17 工廠。你需要自行選擇實作。例如，你可以搭配使用以 Guzzle 為基礎的用戶端及其 PSR-17 工廠，或是搭配使用 Symfony HTTP 用戶端與 nyholm/psr7。任何符合相關 PSR 合約的實作都能運作，因為橋接只相依於這些介面，而非特定程式庫。

步驟 1 — 安裝套件

使用 Composer 加入套件：

composer require nextpdf/gotenberg

這會解析 nextpdf/core ^3.0 以及 PSR HTTP 合約：psr/http-client、psr/http-factory 與 psr/log。它不會安裝具體的 HTTP 用戶端。

步驟 2 — 安裝 PSR-18 用戶端與 PSR-17 工廠

安裝一個 PSR-18 用戶端與一組相符的 PSR-17 工廠。 使用 Guzzle：

composer require guzzlehttp/guzzle guzzlehttp/psr7

或使用 Symfony HTTP 用戶端與 Nyholm PSR-7：

composer require symfony/http-client nyholm/psr7

橋接會透過建構式引數接收這些物件。它本身絕不會自行建構 HTTP 用戶端。因此，選擇權完全在你手上，並由你在組裝橋接時決定。建構式的形式請參閱 /integrations/gotenberg/configuration/，完整的組裝範例請參閱 /integrations/gotenberg/quickstart/。

步驟 3 — 架設 Gotenberg 服務

橋接會呼叫 Gotenberg 的 LibreOffice 轉換路由，因此你需要一個橋接能連線的 Gotenberg 執行個體。上游專案有發布容器映像檔。本機開發的標準指令為：

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

這會在連接埠 3000 上以純 HTTP 公開 Gotenberg，僅適用於本機開發。橋接對設定的 API URL 要求使用 HTTPS。它會在送出任何請求之前，先拒絕純 http://。對於本機實驗以外的任何情境，請將 Gotenberg 置於負責 TLS 終結的反向代理或服務網格之後，再將橋接指向該 HTTPS 端點。/integrations/gotenberg/security-and-operations/ 涵蓋了生產環境的部署形式、網路曝險面與身分驗證。

此處所示的映像檔標籤（gotenberg/gotenberg:8）是上游 Gotenberg 的主要版本線。本專案自己的 README 與整合基準都參照該版本線。在生產環境中，請固定到特定的修補版本標籤，而非追蹤會持續變動的主要版本標籤。此外，也請驗證路由路徑（/forms/libreoffice/convert、/health）是否符合你所部署的 Gotenberg 版本。橋接會假設這兩個路徑存在，並且不對該服務做出其他任何假設。

步驟 4 — 驗證接線

到目前為止，套件與 HTTP 用戶端皆已安裝，且 Gotenberg 可透過 HTTPS 連線。在你嘗試實際轉換之前，請先使用內建的健康檢查探測器，確認橋接看得見該服務：

<?php

declare(strict_types=1);

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

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

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

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() 會先驗證所設定的 URL。對於空白、非 HTTPS 或私有位址的 URL，它會在完全不送出任何網路流量的情況下傳回 false。接著它會向 <apiUrl>/health 送出一個 HEAD 請求，並在狀態碼低於 500 時回報該服務可用。網路錯誤會被攔截並回報為不可用，而非被拋出。

版本說明

本文件描述的是套件 ^3.0 版本線。該版本線與 composer.json 的需求以及 SECURITY.md 的支援矩陣相符，其中 3.x 受支援而 2.x 不受支援。存放庫內骨架頁面中較早的 0.x 參照早於 3.0 版本線，而 composer.json 的限制會取代它們。

另請參閱

• /integrations/gotenberg/overview/ — 橋接的功能以及它能轉換的格式。
• /integrations/gotenberg/configuration/ — 每個建構式引數與設定欄位。
• /integrations/gotenberg/quickstart/ — 一個完整、可執行的第一次轉換。
• /integrations/gotenberg/security-and-operations/ — 如何安全地運作 Gotenberg 相依服務。
• /integrations/gotenberg/boot-and-discovery/ — 框架自動接線。