NextPDF Gotenberg の設定

概要

設定は 2 か所に分かれています。1 つ目は、サービスとその制限を記述するイミュータブルな GotenbergConfig 値オブジェクトです。2 つ目は、PSR HTTP のコラボレーターを組み込む GotenbergBridge コンストラクターです。どちらも明示的なコンストラクターインジェクションです。グローバル状態、パッケージ内部での環境変数の読み取り、隠れたデフォルトエンドポイントはいずれもありません。

設定オブジェクト

GotenbergConfig は final readonly な値オブジェクトです。名前付き引数で直接構築するか、連想配列から GotenbergConfig::fromArray() で構築します。

フィールド

フィールド	型	デフォルト	効果
`apiUrl`	`string`	`''`	Gotenberg サービスのベース URL。必須。空の値は設定を無効にし、すべての変換が即座に失敗します。HTTPS でなければなりません。
`timeout`	`int`	`30`	転送のハードタイムアウト（秒単位）。cURL ピン留めトランスポートが選択されたときに適用されます。
`maxFileSize`	`int`	`52_428_800`	入力の最大サイズ（バイト単位、50 MiB）。これを超える入力は、リクエストを送信する前に拒否されます。
`apiKey`	`string`	`''`	Bearer トークン。空でない場合は `Authorization: Bearer <token>` ヘッダーとして送信されます。スタックトレースで秘匿されるよう `#[\SensitiveParameter]` が付与されています。
`pinnedPublicKeys`	`list<string>`	`[]`	`sha256/<base64>` 形式のプライマリ TLS SPKI ピン。空の場合はピン留めを無効化します。
`backupPublicKeys`	`list<string>`	`[]`	バックアップの TLS SPKI ピン。ローテーションを独立して検証できるよう、別個に保持されます。

直接構築する

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    maxFileSize: 20 * 1024 * 1024,
    apiKey: $secretFromYourSecretStore,
);

配列から構築する

fromArray() は snake_case のキーを受け付け、不正な値は例外を投げずに無視します。文字列でない api_url は '' になります。整数でない timeout は 30 にフォールバックします。整数でない max_file_size は 50 MiB のデフォルトにフォールバックします。配列でないピンリストは [] になります。ピン配列内の文字列でないエントリーは破棄されます。

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

この寛容なパースは意図的なものです。これにより、事前検証層を置かずにフレームワークの設定配列をそのまま渡し、型付けされたオブジェクトを生成できます。URL に到達可能であることや、ピンが正しいことは検証しません。これらのチェックは変換時に行われます。

有効性

isValid() は、apiUrl が空でない文字列の場合にのみ true を返します。ネットワークやスキームのチェックは行いません。HTTPS とプライベートアドレスのスクリーニングは、変換時にセキュリティポリシー内で行われます。設定が無効な場合、convertFile() と convertString() はメッセージ Invalid Gotenberg configuration: apiUrl is empty を伴う GotenbergConvertException をスローします。また、無効な設定では、ネットワーク呼び出しなしで isAvailable() が false を返します。

ブリッジコンストラクター

GotenbergBridge は、設定に加えて PSR コラボレーターを受け取ります。

引数	型	必須	効果
`config`	`GotenbergConfig`	はい	上記で説明したサービス記述子と制限。
`httpClient`	`Psr\Http\Client\ClientInterface`	はい	ヘルスプローブと、フォールバックトランスポートとして使用される PSR-18 クライアント。
`requestFactory`	`Psr\Http\Message\RequestFactoryInterface`	はい	PSR-7 リクエストを構築します。
`streamFactory`	`Psr\Http\Message\StreamFactoryInterface`	はい	リクエストボディのストリームを構築します。
`logger`	`Psr\Log\LoggerInterface\|null`	いいえ（デフォルト `null`）	指定された場合、変換リクエストごとに `debug` レベルのエントリーが記録されます。
`htmlSecurityPolicy`	`HtmlSecurityPolicyInterface\|null`	いいえ	デフォルトでは、コアのデフォルト HTML セキュリティポリシーが使われます。パース層のポリシーであり、トランスポート層のポリシーを補完します。
`responseFactory`	`Psr\Http\Message\ResponseFactoryInterface\|null`	いいえ（デフォルト `null`）	cURL ピン留めトランスポートを有効化するために必要です。これがない場合、ブリッジは常に注入された PSR-18 クライアントを使用します。

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

トランスポートの選択

ブリッジには 2 つのトランスポートがあり、変換リクエストごとにどちらか一方を選択します。

cURL ピン留めトランスポート — responseFactory が注入され、かつピン留めの対象があるとき（URL が 1 つ以上の IP に解決された、または SPKI ピンが設定されている）に使用されます。このトランスポートは、解決済みのアドレスセットを CURLOPT_RESOLVE でバインドします。ピンが存在する場合は CURLOPT_PINNEDPUBLICKEY で SPKI ピン留めを強制します。ピアとホストを検証します（CURLOPT_SSL_VERIFYPEER、CURLOPT_SSL_VERIFYHOST = 2）。設定されたタイムアウトを適用し、リダイレクト追従を無効化 します（CURLOPT_FOLLOWLOCATION = false、CURLOPT_MAXREDIRS = 0）。
注入された PSR-18 クライアント — それ以外のすべてのケースで使用されます。たとえば、API URL がパブリックな IP リテラル（ピン留めする DNS がない）で、SPKI ピンも設定されていない場合や、responseFactory が指定されなかった場合などです。

実務上、DNS リバインディングに耐性のある接続と TLS ピン留めを得るには、responseFactory を注入し、ピンを設定してください。ヘルスプローブは、トランスポートの選択にかかわらず、常に注入された PSR-18 クライアントを使用します。

TLS 公開鍵ピン留め

ピン留めは SHA-256 SPKI フィンガープリントモデルに従います。各ピンは sha256/<base64-encoded-spki-hash> 形式の文字列です。このトランスポートは cURL ネイティブの sha256//<base64> 形式も受け付け、シングルスラッシュ形式をその形式に変換します。それ以外のプレフィックスは InvalidSpkiPinException を発生させます。

allPublicKeyPins() は、pinnedPublicKeys と backupPublicKeys の重複排除済みの和集合を返します。TLS 層は、SPKI ハッシュがその結合集合の いずれか のメンバーと一致する証明書を受け入れます。運用上は、計画的な証明書や鍵のローテーション時に、新しい鍵が伝播するまでブリッジがサービスから締め出されないよう、少なくとも 1 つのバックアップピンを設定すべきです。バックアップリストをプライマリリストと別個に保つことで、アクティブなピンとは独立してバックアップピンを検証し、ローテーションできます。ローテーション手順については /integrations/gotenberg/security-and-operations/ を参照してください。

リクエストごとの変換オプション

マルチパートのペイロード型（GotenbergConvertPayload）は、ファイルに加えて 2 つの任意の Gotenberg 変換オプションを保持します。

landscape（bool、デフォルト false） — landscape フォームフィールドとして、"true" または "false" で送信されます。
nativePageRanges（string、デフォルト ''） — 空でないときにのみ nativePageRanges フォームフィールドとして送信されます。1-3 や 1,3,5-9 といった Gotenberg のレンジ構文を受け付けます。

パブリックな convertFile() および convertString() のエントリーポイントは、これら 2 つのフィールドにデフォルト値を使ってペイロードを構築します。これらのフィールドはペイロード契約の一部であり、テストスイートで動作確認されています。横向き出力やページ選択が必要な場合は、自前の連携層からこれらを公開してください。