Gotenberg API リファレンス

概要

Gotenberg パッケージは、サービスブリッジ GotenbergBridge を 1 つ公開します。これは Office ドキュメント（docx、xlsx、pptx、odt、ods、odp）を外部 Gotenberg サービスに POST して PDF に変換します。そのブリッジの周囲には、読み取りや受け渡しに使う補助的な値オブジェクトが配置されています。GotenbergConfig（イミュータブルなサービス記述子と制限値）、OfficeFormat（サポート対象フォーマットの列挙型）、GotenbergConvertPayload（マルチパートのリクエストボディ）、GotenbergConvertResult（パース済みの PDF レスポンス）です。第 2 階層の GotenbergSecurityPolicy、GotenbergResponseParser、PinnedCurlTransport は、ブリッジが内部で駆動する検証、パース、ピン留めトランスポートの仕組みです。これらを直接使うのは、カスタムトランスポートやテストコードを書く場合だけです。

ここから始めてください。 HTTPS のサービス URL を指定して GotenbergConfig を構築し、PSR-18 クライアントと PSR-17 ファクトリとともに GotenbergBridge に渡します。その後、convertFile() または convertString() を呼び出し、返された GotenbergConvertResult から pdfData を読み取ります。

よく行うタスク

ここでは、このパッケージで実際によく行うタスクを取り上げ、それぞれに検証済みで実行可能なスニペットを添えています。

ディスク上のファイルを PDF に変換する

ブリッジにパスを渡します。フォーマットは拡張子から検出されます。

<?php

declare(strict_types=1);

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: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    responseFactory: $psrResponseFactory,
);

$result = $bridge->convertFile('/path/to/report.docx');

\file_put_contents('/path/to/report.pdf', $result->pdfData);

動作：URL、パス、サイズ、ファイル名を検証し、マルチパートリクエストを 1 回送信して、返された PDF バイト列をディスクに書き込みます。

メモリ上のバイト列を PDF に変換する

すでにバイト列を保持している場合は convertString() を使います。ファイル名によってフォーマットが検出されます。

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

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

動作：ファイル名から xlsx を検出してバイト列を変換し、使用前に結果が %PDF シグネチャで始まることを確認します。

変換前にサービスの準備状態を確認する

変換前に isAvailable() で処理を制御します。これはトラフィックを発生させずに URL を検証し、その後 /health に HEAD を 1 回送信します。

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

動作：空、非 HTTPS、またはプライベートアドレスの URL、およびあらゆるネットワークエラーに対して false を返し（例外はスローしません）、変換をディスパッチする前に早い段階で失敗として扱えます。

ブリッジ

この表はブリッジの公開 API です。GotenbergBridge を構築するときや、変換メソッド、準備状態メソッドを呼び出すときに使用します。

シンボル	パラメーター	既定の動作	戻り値	スローまたは失敗する条件	備考
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	構成、PSR-18 クライアント、PSR-17 ファクトリ、任意のロガー、任意の HTML ポリシー、任意のレスポンスファクトリ。	ポリシーが指定されていない場合は `DefaultHtmlSecurityPolicy` を使用します。	`GotenbergBridge`	コンテナのワイヤリングエラー。	ピン留めが必要な場合は、レスポンスファクトリによってピン留め cURL トランスポートが有効になります。
`GotenbergBridge::convertFile(string $filePath)`	Office ドキュメントへのファイルシステムパス。	フォーマット検出にファイル拡張子を使用します。	`GotenbergConvertResult`	`GotenbergConvertException`、`RuntimeException`、サポートされていないフォーマットの場合は `ValueError`。	実パスを resolve（解決）し、読み取り可能かどうか、サイズ、ファイル名を確認します。
`GotenbergBridge::convertString(string $content, string $fileName)`	生のバイト列と元のファイル名。	フォーマット検出にファイル名の拡張子を使用します。	`GotenbergConvertResult`	失敗条件は `convertFile` と同じ。	アプリケーションがすでにファイルのバイト列を保持している場合に使用します。
`GotenbergBridge::isAvailable()`	なし。	構成が有効な場合は `/health` への HEAD リクエスト。	`bool`	エラー時には `false` を返します。	準備状態シグナルのみ。
`GotenbergBridge::getHtmlSecurityPolicy()`	なし。	構成済みのパース層ポリシーを返します。	`HtmlSecurityPolicyInterface`	想定されません。	トランスポート層のセキュリティポリシーを補完します。

構成とペイロード

この表は、手作業で構築する値オブジェクト、すなわち GotenbergConfig サービス記述子と、リクエストおよびレスポンスを保持する GotenbergConvertPayload/GotenbergConvertResult を対象とします。2 つの変換エントリポイントより細かい制御が必要なときに使用します。

シンボル	パラメーター	既定の動作	戻り値	スローまたは失敗する条件	備考
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	API URL、タイムアウト、最大ファイルサイズ、ベアラートークン、ピンのセット。	空の URL は無効です。既定の最大サイズは 50 MiB です。	`GotenbergConfig`	想定されません。	API キーは秘密にしてください。
`GotenbergConfig::fromArray(array $config)`	`api_url`、`timeout`、`max_file_size`、`api_key`、ピン配列。	指定されていない値はコンストラクターの既定値を使用します。	`GotenbergConfig`	想定されません。	文字列リストでは、文字列以外の値を無視します。
`GotenbergConfig::isValid()`	なし。	API URL が空でなければ有効です。	`bool`	想定されません。	URL の安全性はネットワーク I/O の前に検証されます。
`GotenbergConfig::allPublicKeyPins()`	なし。	プライマリとバックアップのピンを結合します。	`list<string>`	想定されません。	空のリストはピン留めを無効にします。
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	ファイル名、バイト列、フォーマット、向きフラグ、ページ範囲。	縦向き、全ページ。	`GotenbergConvertPayload`	想定されません。	ペイロードはマルチパートフォームデータに変換されます。
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	マルチパート境界。	ページ範囲フィールドは、空でない場合にのみ含めます。	`string`	想定されません。	境界はブリッジによって生成されます。
`GotenbergConvertPayload::contentType(string $boundary)`	マルチパート境界。	既定で `multipart/form-data` を使用します。	`string`	想定されません。	リクエストの `Content-Type` として設定します。
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	変換後の PDF バイト列、ソースフォーマット、任意のレンダリング所要時間。	計測されない場合、レンダリング所要時間は `0.0` です。	`GotenbergConvertResult`	想定されません。	戻り値は `GotenbergResponseParser::parse()` が返します。
`GotenbergConvertResult::isValid()`	なし。	変換後の PDF バイト列が空でなく、PDF データのように見える場合に有効です。	`bool`	想定されません。	結果を保存またはストリーミングする前に確認します。
`GotenbergConvertResult::size()`	なし。	変換後の PDF バイト列のサイズを数えます。	`int`	想定されません。	クォータ、テレメトリ、レスポンス上限に使用します。

Office フォーマット

この表は OfficeFormat 列挙型を対象とします。拡張子をフォーマットにマッピングする、アップロード用 MIME タイプを読み取る、サポートされる 6 つのフォーマットを確認する、といった場合に使用します。

シンボル	パラメーター	既定の動作	戻り値	スローまたは失敗する条件	備考
`OfficeFormat::fromExtension(string $ext)`	先頭にドットがあってもなくてもよいファイル拡張子。	大文字小文字を区別しない照合。	`OfficeFormat`	`ValueError`（サポートされていない拡張子の場合）。	サポートされる値：`docx`、`xlsx`、`pptx`、`odt`、`ods`、`odp`。
`OfficeFormat::mimeType()`	なし。	列挙ケースをアップロード用 MIME タイプにマッピングします。	`string`	想定されません。	マルチパートのファイルパートで使用されます。
`OfficeFormat::extension()`	なし。	列挙ケースの backed value を返します。	`string`	想定されません。	診断やファイル名に役立ちます。

セキュリティ、パース、トランスポート

この表は、ブリッジがユーザーの代わりに駆動する内部の仕組みをまとめたものです。カスタムトランスポート、パッケージのパースを利用する独自の HTTP 呼び出し、低レベルのセキュリティ診断やピン留め診断を書く場合にのみ使用します。

シンボル	パラメーター	既定の動作	戻り値	スローまたは失敗する条件	備考
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	API のベース URL。	ネットワーク I/O の前に宛先をパースして検証します。	`array`	`RuntimeException`（安全でない、または無効な URL の場合）。	SSRF に似た誤ったエンドポイントを変換コードから締め出します。
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	ホストとピン留めされた IP リスト。	DNS がピンの期待値と一致するか検証します。	`void`	`RuntimeException`（ピンが古いか無効な場合）。	ピン留めされたデプロイや運用診断で使用します。
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	実際のサイズと構成された最大値。	構成された上限以下のファイルを受け入れます。	`void`	`RuntimeException`（ファイルが大きすぎる場合）。	リクエスト構築の前に適用します。
`GotenbergSecurityPolicy::validateFileName(string $name)`	元のファイル名。	安全でない、またはサポートされていないファイル名形式を拒否します。	`void`	`RuntimeException`（無効な名前の場合）。	不正なマルチパートファイル名を防ぎます。
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	PSR-7 レスポンスと期待される Office フォーマット。	成功レスポンスから変換後の PDF バイト列を抽出します。	`GotenbergConvertResult`	`GotenbergConvertException`（レスポンスの失敗または無効な PDF 出力の場合）。	ファイル変換と文字列変換の両方で共通のパーサーです。
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	PSR-17 ファクトリ、ピン留めされた IP、ピン留めされた公開鍵、タイムアウト。	ピンなし、30 秒のタイムアウト。	`PinnedCurlTransport`	想定されません。	cURL レベルのピン留めが必要な場合にのみ使用します。
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	PSR-7 リクエスト。	構成されたタイムアウトとピン留め制御で cURL 経由で送信します。	`ResponseInterface`	`GotenbergConvertException`（cURL/トランスポートの失敗時）。	ピン留めを別の HTTP クライアントに委譲できない場合に使用します。
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	リクエスト、ホスト、ポート。	内部で `sendRequest()` が使用する cURL オプション配列を構築します。	`array`	無効なリクエストまたはピン構成エラー。	低レベル診断およびテストフック。

開発上の注意

Gotenberg は外部サービス境界として扱ってください。タイムアウト、サイズ、URL、ピンポリシーを意図的に構成してください。
convertFile() は、リクエスト構築の前にファイル全体をメモリに読み込みます。
ファイル内容ではなく、ファイル名やコンテンツ長などのメタデータをログに記録してください。