Gotenberg 開発者ガイド

概要

Gotenberg パッケージは、変換処理を外部サービスに委譲します。アプリケーションコードでは、サービス境界を明確にする必要があります。つまり、入力を検証し、ペイロードを構築し、リクエストを送信し、結果を解析し、サービス障害に対処します。

office から PDF への変換ワークフロー、アップロードエンドポイント、サービスヘルスチェック、または nextpdf/gotenberg 周辺のトランスポートポリシーを構築する際に、このガイドを参照してください。

アーキテクチャ境界

レイヤー	所有者	責務	ここに置かないもの
アップロードまたはドキュメントソース	アプリケーション	呼び出し元の認可、ソースの検証、変換ポリシーの選択。	サービス URL またはトランスポートのピン留めに関する判断。
フォーマット検出	nextpdf/gotenberg	安全な拡張子から OfficeFormat へのマッピング。	アプリケーション側の検証を伴わない MIME の信頼。
ブリッジ	nextpdf/gotenberg	マルチパートリクエストの構築、Gotenberg の呼び出し、PDF レスポンスの解析。	ドメインクエリまたはストレージポリシー。
Gotenberg サービス	デプロイメント	office ドキュメントから PDF への変換。	PHP アプリケーションの認可。
コアエンジン	nextpdf/nextpdf	変換済み PDF データの必要に応じたインポートまたは結合。	office ドキュメントの変換。

ランタイムライフサイクル

ステージ	動作	開発者のアクション
設定の作成	API URL、タイムアウト、最大サイズ、API キー、ピンの読み込み。	サービス URL とトークンのソースコード外での管理。
入力検証	ファイルパス、ファイルサイズ、ファイル名、拡張子、URL の安全性チェック。	ディスパッチ前の、サポートされていない入力の拒否。
ペイロードの構築	GotenbergConvertPayload によるマルチパートフォームデータの構築。	安全な場合に限る、元のファイル名の保持。
サービスリクエスト	ブリッジによる /forms/libreoffice/convert へのリクエスト送信。	タイムアウトとトランスポートポリシーの設定。
結果の解析	GotenbergResponseParser::parse() による PDF バイトとメタデータの返却。	PDF 以外またはエラーレスポンスの、変換失敗としての扱い。

推奨されるアプリケーション構成

パス	目的
app/Pdf/Conversion/*	内部で GotenbergBridge をラップするアプリケーションラッパー。
app/Pdf/Uploads/*	アップロードの検証、ストレージ、ファイル名ポリシー。
app/Pdf/ConversionPolicy/*	サイズ、フォーマット、サービス選択のポリシー。
tests/Pdf/Conversion/*	フォーマット、ファイル、サービス、トランスポートのテスト。

ファイル検証は変換から分離してください。変換サービスは、すでに認可済みの入力を受け取るべきですが、それでも多層防御としてパッケージ側の検証に依拠してください。

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

        if (!$result->isValid()) {
            throw new RuntimeException('The conversion service did not return a valid PDF.');
        }

        return $result->pdfData;
    }
}

変換パターン

パターン	API	使用する場面	制約
ファイルパスの変換	GotenbergBridge::convertFile()	すでにディスクに保存されているドキュメント。	読み取り可能で、ポリシーで承認済みであることが必要なパス。
メモリ上のバイト列の変換	GotenbergBridge::convertString()	アプリケーションがすでに保持している、アップロードまたはオブジェクトストア由来のバイト列。	引き続きファイル名がフォーマット検出を制御すること。
ペイロードを直接構築	GotenbergConvertPayload	テストまたはカスタムトランスポートコードで必要になるマルチパートのバイト列。	境界の生成をユーザー入力の外部に保つこと。
レスポンスを直接解析	GotenbergResponseParser::parse()	カスタム HTTP 呼び出しでも利用したい、パッケージによる解析。	想定される OfficeFormat の指定が必要。

ヘルスとレディネス

GotenbergBridge::isAvailable() はレディネスシグナルです。これを唯一のランタイムガードにしてはいけません。サービスはレディネス時点では利用可能でも、次の変換で失敗する可能性があります。

チェック	目的	運用上の注記
設定の妥当性	API URL 欠落の検出。	アプリ起動時またはデプロイメントチェック時の実行。
/health の可用性	到達可能なサービスの検出。	レディネスダッシュボードでの利用。
小さなフィクスチャの変換	故障した LibreOffice またはサービスリグレッションの検出。	リクエストごとではなく、スケジュールされたスモークテストでの実行。
タイムアウトの監視	遅いサービス動作の検出。	フォーマットとファイルサイズ別の追跡。

拡張ポイント

拡張ポイント	用途	制約
PSR-18 ClientInterface	カスタム HTTP クライアント動作。	PSR-18 の response/exception セマンティクスへの準拠。
PSR-17 ファクトリ	リクエストとストリームの作成。	ブリッジ構築に必要。
HtmlSecurityPolicyInterface	HTML 入力に対する解析レイヤーのポリシー。	Gotenberg のセキュリティポリシーの補完。
ResponseFactoryInterface	ピン留めされた cURL トランスポートのレスポンス構築。	パッケージのトランスポートパス使用時のみ必要。
GotenbergSecurityPolicy	URL、ファイルサイズ、ファイル名、ピンの検証。	アプリケーションの認可は、このレイヤーの外部で扱うこと。

開発ワークフロー

1. フィクスチャを明示しやすくするため、テストではまず convertString() から始めます。
2. ファイルシステムのパス制御を確立してからのみ convertFile() を追加します。
3. 最大ファイルサイズを、サービスおよびインフラストラクチャの制限より小さく保ちます。
4. エラー処理の代替としてではなく、レディネスシグナルとして isAvailable() を使用します。
5. ファイル名、フォーマット、サイズ、ステータス、所要時間をログに記録します。ドキュメントのバイト列はログに記録しないでください。
6. アップロードエンドポイントを公開する前に、タイムアウトと障害モードのテストを追加します。

障害処理

障害	処理すべき場所	推奨される対応
サポートされていない拡張子	フォーマット検出。	サービスへのディスパッチ前の拒否。
安全でないファイル名	セキュリティポリシー。	拒否と、アップロードの命名ポリシーの正規化。
サイズ超過ファイル	アップロードポリシーとパッケージの検証。	大きなペイロードを読み取ったり送信したりする前の拒否。
Gotenberg が利用不可	ブリッジ境界。	適切な場合の、リトライ可能なアプリケーションエラーの返却。
PDF 以外のレスポンス	レスポンスパーサー。	変換失敗としての扱いと、サービスステータスの記録。
ピンまたは URL の検証失敗	トランスポートポリシー。	フェイルクローズと、運用担当者へのアラート通知。

安全なデフォルト

対象	デフォルト	オーバーライドすべき場面
タイムアウト	30 秒。	実際のサービスレイテンシを測定した後に限る引き上げ。
最大ファイルサイズ	52,428,800 バイト。	公開エンドポイントまたはマルチテナントエンドポイントでの引き下げ。
API キー	空。	プライベートな Gotenberg デプロイメント向けの設定。
サポートされるフォーマット	docx、xlsx、pptx、odt、ods、odp。	追加する形式が OfficeFormat とパーサーでサポートされている場合のみ。
ピンセット	空。	バックアップピンとローテーション手順を伴うピンの追加。

テストチェックリスト

• フォーマットのテストでは、サポートされる拡張子とサポートされない拡張子を対象とします。
• ファイルのテストでは、欠落、読み取り不可、サイズ超過、安全でないファイル名を対象とします。
• サービスのテストでは、2xx 以外のレスポンス、無効なレスポンスボディ、トランスポート例外を対象とします。
• セキュリティのテストでは、ポリシーで禁止されるプライベートまたは無効なサービス URL を対象とします。
• タイムアウトのテストでは、設定されたタイムアウトがトランスポートに渡されることを検証します。
• フィクスチャのテストでは、サンプルドキュメントを小さく、機微情報を含まないものに保ちます。