NextPDF Cloudflare ブリッジの構成

概要

3 つのイミュータブルな構成オブジェクトで、パッケージの動作を制御します。このページに記載するすべてのデフォルトは、src/Cloudflare/ 内の対応するコンストラクターシグネチャから読み取ったものです。仕様や見積もりに基づくものではありません。このページで最大値を示す場合、その最大値はこのパッケージが強制する上限です。Cloudflare プラットフォームの容量を示すものではありません。

`CloudflareRendererConfig`

レンダラーの構成です。final readonly。直接構築するか、CloudflareRendererConfig::fromArray() で構築します。

フィールド	型	デフォルト	意味
`workerUrl`	`string`	— (必須)	Worker エンドポイント URL。HTTPS 必須。
`apiToken`	`string`	— (必須)	Bearer トークン。`#[SensitiveParameter]` でマーク済み。
`renderTimeout`	`int`	`30`	ピン留めされた cURL トランスポートが適用する転送タイムアウト (秒)。
`defaultCss`	`string`	`''`	HTML より前にペイロードへ挿入される CSS。
`maxHtmlSize`	`int`	`5000000`	リクエスト送信前に強制される HTML 入力の最大サイズ (バイト単位)。
`r2FontBucket`	`?string`	`null`	カスタムフォントパッケージ用の R2 バケット名。
`fallbackToLocal`	`bool`	`true`	Worker に到達できない場合のローカルレンダラーへのフォールバック有無。
`pinnedPublicKeys`	`list<string>`	`[]`	SHA-256 SPKI フィンガープリント。形式は `sha256/<base64>`。
`backupPublicKeys`	`list<string>`	`[]`	バックアップ用 SPKI ピン。ローテーションを独立して検証できるよう、別管理。

isValid() が true を返すのは、workerUrl !== '' かつ apiToken !== '' の場合だけです。allPublicKeyPins() は、pinnedPublicKeys と backupPublicKeys の重複を除いた和集合を返します。TLS 層は、その和集合のいずれかのメンバーに SPKI ハッシュを含む証明書を受け入れます。これは RFC 7469 §2.6 と一致します。同条項では、提示された SPKI フィンガープリントの集合がピン留め済みの集合と交差した場合に、ピン留め接続を検証します。RFC 7469 §2.5 では、バックアップピンを、意図しないピン検証失敗に対する主要な復旧手段として説明しています。証明書ローテーションでエンドポイントが壊れないよう、バックアップピンを少なくとも 1 つ保持してください — /integrations/cloudflare/security-and-operations/. を参照してください。

`fromArray()` キーマップ

CloudflareRendererConfig::fromArray() は snake_case キーを読み取り、キーが存在しない場合、または型が誤っている場合は同じデフォルトを適用します。

配列キー	マッピング先
`worker_url`	`workerUrl`
`api_token`	`apiToken`
`render_timeout`	`renderTimeout` (デフォルト `30`)
`default_css`	`defaultCss`
`max_html_size`	`maxHtmlSize` (デフォルト `5000000`)
`r2_font_bucket`	`r2FontBucket`
`fallback_to_local`	`fallbackToLocal` (デフォルト `true`)
`pinned_public_keys`	`pinnedPublicKeys` (文字列でないメンバーは破棄)
`backup_public_keys`	`backupPublicKeys` (文字列でないメンバーは破棄)

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => 'https://pdf-renderer.example.workers.dev/render',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => 'pdf-fonts',
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

パッケージが強制する入力サイズ上限

これらの上限は、リクエストがプロセスを離れる前に CloudflareSecurityPolicy::validate() によって強制されます。数値はソースから読み取ったものです。

上限	値	場所
HTML 入力の最大サイズ	`maxHtmlSize` (デフォルト `5000000` バイト)	`CloudflareSecurityPolicy::validate()`
デコード後の base64 data-URI の最大サイズ	`13631488` バイト (≈13 MB)	`CloudflareSecurityPolicy::MAX_DATA_URI_BYTES`

いずれかを超過すると RuntimeException が発生し、違反したサイズと上限を示すメッセージが付随します。base64 の上限は、解凍爆弾への防御です。ポリシーは base64 の長さからデコード後のサイズを推定し、上限以上であれば拒否します。<meta http-equiv="refresh"> タグも、大文字小文字を区別せず拒否されます。レンダリング済みページ内からリダイレクトを引き起こせるためです。

このパッケージは、自身が強制する上限のみを記述します。Worker 自体のリクエスト、CPU、メモリ上限については、いかなる主張もしません。それらについては、 Cloudflare の公式ドキュメントと、ご自身の Worker 実装を参照してください。

`ApiProtectionConfig`

Worker、またはその前段にある PHP ゲートウェイが受信レンダーリクエストに適用する、任意のリクエスト保護層の構成です。final readonly。

フィールド	型	デフォルト	意味
`maxRequestsPerMinute`	`int`	`60`	クライアント単位、分単位のリクエスト上限。
`maxRequestsPerHour`	`int`	`1000`	クライアント単位、時間単位のリクエスト上限。
`maxPayloadSizeBytes`	`int`	`10485760`	受信ペイロードの最大サイズ (≈10 MB)。
`allowedOrigins`	`list<string>`	`[]`	CORS 許可リスト。空の場合、この構成ではオリジン制限を表現しないという意味。
`requireApiKey`	`bool`	`true`	API キー必須化の有無。
`apiKeyHeader`	`string`	`'X-Api-Key'`	API キーを運ぶヘッダー。
`rateLimitWindowSeconds`	`int`	`60`	分単位ウィンドウの長さ (秒)。

fromArray() は max_requests_per_minute、max_requests_per_hour、max_payload_size_bytes、allowed_origins、require_api_key、api_key_header、rate_limit_window_seconds を読み取ります。isValid() は、すべての数値フィールドが正であり、apiKeyHeader が空でないことを要求します。

`R2ArchiveConfig`

レンダリングされた PDF を、S3 互換 API を介して Cloudflare R2 へアーカイブするための構成です。final readonly。

フィールド	型	デフォルト	意味
`bucketName`	`string`	— (必須)	R2 バケット。S3 命名規則に照らして検証されます。
`accountId`	`string`	— (必須)	デフォルトエンドポイントの構築に使う Cloudflare アカウント ID。
`accessKeyId`	`string`	— (必須)	R2 アクセスキー ID。`#[SensitiveParameter]`。
`secretAccessKey`	`string`	— (必須)	R2 シークレットアクセスキー。`#[SensitiveParameter]`。
`endpoint`	`string`	`''`	カスタム S3 エンドポイント。空の場合、`accountId` からデフォルトを構築します。
`pathPrefix`	`string`	`'pdfs/'`	アップロードされるオブジェクトのキープレフィックス。
`maxFileSizeBytes`	`int`	`104857600`	アップロードの最大サイズ (≈100 MB)。アップロード前に強制されます。

コンストラクターは、空でない bucketName が S3 互換規則に一致しない場合に拒否します。その規則は次のとおりです。3〜63 文字、英小文字・数字・ハイフンで構成し、先頭と末尾は英数字。違反すると InvalidArgumentException が発生します。isValid() は、bucketName、accountId、accessKeyId、secretAccessKey が空でないことを要求します。endpoint が空の場合、getEndpoint() は https://<accountId>.r2.cloudflarestorage.com を返します。

シークレットの取り扱い

apiToken、accessKeyId、secretAccessKey は #[SensitiveParameter] 属性を持つため、PHP はスタックトレース上でこれらを秘匿します。これらの値は環境変数またはシークレットマネージャーから供給してください。決してコミットしないでください。構成オブジェクトはイミュータブルなため、一度設定した値は構築後に変更できません。

NextPDF Cloudflare ブリッジの構成

概要

CloudflareRendererConfig

fromArray() キーマップ

パッケージが強制する入力サイズ上限

ApiProtectionConfig

R2ArchiveConfig

シークレットの取り扱い

関連項目

`CloudflareRendererConfig`

`fromArray()` キーマップ

`ApiProtectionConfig`

`R2ArchiveConfig`