NextPDF Gotenberg のインストール

概要

ブリッジのインストールは 2 つのパートに分かれます。1 つ目は PHP パッケージとその PSR HTTP 依存関係で、Composer でインストールします。2 つ目は、パッケージが呼び出す 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 ファクトリのインストール

1 つの 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

これにより Gotenberg はポート 3000 で平文 HTTP として公開されますが、これはローカル開発専用です。ブリッジは、設定された API URL に対して HTTPS を必須 とします。いかなるリクエストも送信される前に、平文の http:// を拒否します。ローカルでの検証を超える用途では、Gotenberg を TLS 終端を行うリバースプロキシまたはサービスメッシュの背後に配置し、そのうえでブリッジを HTTPS エンドポイントに向けてください。/integrations/gotenberg/security-and-operations/ では、本番環境のデプロイ構成、ネットワーク公開、認証について解説しています。

ここで示しているイメージタグ（gotenberg/gotenberg:8）は、アップストリームの Gotenberg メジャーラインです。このプロジェクト自身の README と統合ベースラインは、そのラインを参照しています。本番環境では、特定のパッチタグに固定し、変動するメジャータグを追跡しないようにしてください。また、ルートパス（/forms/libreoffice/convert、/health）を、デプロイする Gotenberg のバージョンに照らして確認してください。ブリッジはこれら 2 つのパスのみを前提としており、サービスについてそれ以外の前提は一切置きません。

ステップ 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 を検証します。空の URL、HTTPS でない URL、またはプライベートアドレスの URL に対しては、ネットワークトラフィックを一切発生 させずに false を返します。その後、<apiUrl>/health に HEAD リクエストを送信し、ステータスが 500 未満であればサービスを利用可能として報告します。ネットワークエラーはスローせず、捕捉したうえで利用不可として報告します。

バージョンに関する注記

このドキュメントは、パッケージの ^3.0 ラインについて説明しています。このラインは、composer.json の要件、および 3.x がサポート対象で 2.x がサポート対象外である SECURITY.md のサポートマトリクスと一致します。リポジトリ内のスケルトンページにある以前の 0.x への参照は 3.0 ラインより前のものであり、composer.json の制約がそれらに優先します。