NextPDF Gotenberg クイックスタート

概要

このウォークスルーでは、1 つの .docx ファイルを PDF に変換します。最後には、動作するブリッジインスタンス、検証済みのサービス接続、そしてディスク上の PDF という 3 つが手に入ります。完全なプログラムは、リポジトリの examples/convert-office-to-pdf.php にあります。以下のスニペットは、そのプログラムからの抜粋です。

このページはチュートリアルであるため、まず正常系（ハッピーパス）を示します。本番環境での考慮事項（シークレットの取得、リトライ、タイムアウト、可観測性）は、/integrations/gotenberg/production-usage/. で扱います。

始める前に

次の 3 点を確認してください。

composer require nextpdf/gotenberg を実行済みで、PSR-18 クライアントと PSR-17 ファクトリがインストールされていること。 /integrations/gotenberg/install/. を参照してください。
Gotenberg サービスに HTTPS 経由で到達できること。平文の http:// は、リクエストがプロセスを離れる前にブリッジによって拒否されます。
次のいずれかの形式のサンプルファイルがあること: .docx、.xlsx、.pptx、.odt、.ods、または .odp。その他の拡張子は ValueError で拒否されます。

ステップ 1 — サービスを記述する

GotenbergConfig はイミュータブルな値オブジェクトです。少なくとも、Gotenberg サービスの HTTPS ベース URL が必要です。

use NextPDF\Gotenberg\GotenbergConfig;

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

timeout は秒単位の転送タイムアウトで、cURL に固定されたトランスポートによって適用されます。apiKey は、空でない場合に Authorization: Bearer <token> として送信されます。Gotenberg のデプロイでトークンが不要な場合は、apiKey を空のままにしてください。

ステップ 2 — ブリッジを配線する

ブリッジは、設定に加えて PSR コラボレーターを受け取ります。DNS ピンニングおよび TLS ピンニングを行う cURL トランスポートを有効にするため、responseFactory も注入してください。

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

ブリッジが自分で HTTP クライアントを構築することはありません。インストール済みの任意の PSR-18 クライアントと PSR-17 ファクトリを使用してください。サンプルファイルには、Guzzle の配線がコメントで示されています。

ステップ 3 — 可用性を確認する

変換を実行する前に、サービスをプローブしてください。プローブは、ネットワークトラフィックを発生させずに URL を検証し、その後 <apiUrl>/health に HEAD を送信します。

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

isAvailable() は、空、非 HTTPS、またはプライベートアドレスの URL、およびあらゆるネットワークエラーに対して false を返します（例外をスローすることはありません）。/health からの 500 未満のステータスは、サービスが利用可能であることを意味します。

ステップ 4 — 変換する

convertFile() はディスク上のパスを受け取ります。パスは正規化され、トラバーサルを阻止します。拡張子はサポートされている形式にマッピングされます。サイズとファイル名が検査されます。その後、マルチパートリクエストが <apiUrl>/forms/libreoffice/convert に送信されます。

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

すでにメモリに保持しているバイト列を変換するには、convertString() を使用します。ブリッジが拡張子を検出できるように、元のファイル名を渡してください。

$pdf = $bridge->convertString($docxBytes, 'report.docx');

ステップ 5 — 結果を使用する

結果は、PDF のバイト列、ソース形式、および妥当性チェックという 3 つを保持します。

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

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

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

isValid() は、本体が空でなく %PDF で始まる場合に true になります。size() はバイト長です。ここから先、PDF は通常のストリームであり、後処理のために NextPDF に渡すことができます。

完全なプログラム

完全に実行可能なプログラムは、パッケージリポジトリの examples/convert-office-to-pdf.php にあります。このプログラムは、引数の解析、環境変数による設定、ヘルスプローブ、網羅的なエラー処理、および書き込みを扱います。次のように実行します。

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

次のステップ

/integrations/gotenberg/configuration/ — すべてのオプションとトランスポート選択ルール。
/integrations/gotenberg/production-usage/ — シークレット、リトライ、タイムアウト、ロギング、並行処理。
/integrations/gotenberg/troubleshooting/ — このコードがスローしうるすべての例外とその意味。
/integrations/gotenberg/integration/ — サービスを通じて NextPDF のレンダリングパイプラインを駆動する方法。