NextPDF Cloudflare 連携

概要

このページでは、最初から最後までの全工程を扱います。パッケージをインストールし、設定を行い、PDF をレンダリングして、必要に応じて結果をアーカイブします。各ステップでは、Cloudflare Worker と R2 経由で NextPDF のレンダリングを実行します。このハウツーガイドは、概念を説明する /integrations/cloudflare/overview/ と、リファレンスである /integrations/cloudflare/configuration/. に対応しています。

インストール

composer require nextpdf/cloudflare:^0.1

次に、Guzzle 7 などの PSR-18 クライアントと PSR-17 ファクトリーを追加します。このパッケージは PSR の契約のみを宣言し、独自の具体実装クライアントは同梱していないため、利用者側で用意します。詳細については、/integrations/cloudflare/install/. を参照してください。

ブート/自動検出

このブリッジには、サービスプロバイダもバンドルもありません。代わりに、PSR コラボレーターと CloudflareRendererConfig から直接構築します。ホスト側のフレームワークは、アプリケーションの既存の PSR-18 バインディングを再利用し、自身のコンテナにバインドします。完全なブートシーケンスとコンテナバインディングの例については、/integrations/cloudflare/boot-and-discovery/. を参照してください。

コンテナバインディング

CloudflareHtmlRenderer をシングルトンとしてバインドします。PSR-18 クライアント、PSR-17 のリクエストおよびストリームファクトリー、任意の PSR-3 ロガーを渡します。cURL トランスポートをピン留めする場合は、PSR-17 レスポンスファクトリーも渡します。バインディングの例については、/integrations/cloudflare/boot-and-discovery/. を参照してください。

設定の公開

このパッケージは、設定を CloudflareRendererConfig から読み込みます。シークレットは環境から取得し、コミット済みファイルからは決して取得しないでください。

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => getenv('CF_WORKER_URL') ?: '',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => getenv('CF_R2_FONT_BUCKET') ?: null,
]);

workerUrl は HTTPS でなければなりません。apiToken は #[SensitiveParameter] です。フィールドの完全なリファレンスについては、SPKI ピンフィールドとすべてのデフォルトを扱う /integrations/cloudflare/configuration/ を参照してください。R2 アーカイブの設定と API 保護レイヤーについては、/integrations/cloudflare/production-usage/. で説明しています。

サービスプロバイダ/バンドルのスモークテスト

スモークテスト対象のサービスプロバイダはありません。同等のブートチェックは次のとおりです。

$config = CloudflareRendererConfig::fromArray($appConfig['cloudflare']);
assert($config->isValid(), 'Cloudflare config incomplete');

// Optional runtime reachability check (authenticated HTTP HEAD):
if (!$renderer->isAvailable()) {
    // Worker not reachable — degrade or alert.
}

isValid() は単純な完全性チェックであり、ネットワーク呼び出しは行いません。isAvailable() は、認証済みの HEAD を実行します。Worker が停止している場合は、例外をスローせずに false を返します。

公開 API のエントリーポイント

このパッケージの公開 API サーフェスはすべて NextPDF\Cloudflare\ の下にあります。

型	役割
`CloudflareHtmlRenderer`	レンダリングのエントリーポイント。`render()`、`isAvailable()`、`getHtmlSecurityPolicy()`。
`CloudflareRendererConfig`	レンダラーの設定（`fromArray()`、`isValid()`、`allPublicKeyPins()`）。
`CloudflareRenderResult`	型付きレンダリング結果（`isValid()`、`size()`）。
`CloudflareRenderPayload`	Worker の JSON ペイロード（`toJson()`）。
`CloudflareResponseParser`	Worker レスポンス → 結果パーサー。
`CloudflareSecurityPolicy`	入力と URL の検証。
`Transport\PinnedCurlTransport`	DNS ピン留め/TLS ピン留めの PSR-18 トランスポート。
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	ローカルフォールバックの契約。
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	受信 API の保護。
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	R2 アーカイブ。
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	例外階層。

レンダリングの完全なウォークスルーについては、/integrations/cloudflare/quickstart/. を参照してください。本番環境での配線については、フォールバック、テレメトリ、アーカイブ、保護を扱う /integrations/cloudflare/production-usage/ を参照してください。