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 ファクトリは、別パッケージとしてご自身でインストールしてください。ブリッジはインターフェースのみに依存するため、具体的なライブラリはご自身で選択できます。Gotenberg サービスを HTTPS で立ち上げる方法を含む完全なインストール手順については、/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:// を拒否します。Gotenberg は TLS 終端の背後で実行し、ブリッジは HTTPS エンドポイントに向けてください。

コンテナバインディング

ホストコンテナには 3 つの要素を登録します。1 つ目は、設定ソースから構築した GotenbergConfig です。2 つ目は、PSR-18 クライアントと PSR-17 ファクトリの組み合わせです。3 つ目は、それらから組み立てた GotenbergBridge です。このパッケージ自体はバインディングを同梱しません。フレームワークネイティブの登録は、専用のフレームワーク連携パッケージの役割です。/integrations/gotenberg/boot-and-discovery/ を参照してください。

設定

サービスディスクリプタとその制限は、いずれも GotenbergConfig のフィールドです。これらは API URL、タイムアウト、サイズ上限、ベアラトークン、TLS ピンを対象とします。リクエストごとのオプションである landscape と nativePageRanges は、代わりにペイロード型のフィールドです。/integrations/gotenberg/configuration/ では、すべてのフィールドについて型、デフォルト、効果を記載しています。

変換後の PDF を NextPDF パイプラインへ接続する

典型的なエンドツーエンドのフローは次のとおりです。

convertFile() または convertString() で Office ドキュメントを変換します。
生の PDF バイト列を保持する $result->pdfData を取得し、それを 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 を検証します。続いて <apiUrl>/health へ HEAD を送信します。その後、正常であることが分かっている小さなドキュメントを 1 つ変換します。これにより、<apiUrl>/forms/libreoffice/convert までのマルチパート経路全体と、レスポンス検証を一通り実行します。

公開 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/ にあります。そこではトランスポートの選択と例外カタログを取り上げています。