NextPDF Cloudflare 橋接設定

概覽

三個不可變的設定物件管理整個套件。本頁列出的每個預設值，都取自 src/Cloudflare/ 中對應的建構式簽章，並非規格或估算值。本頁標示的任何最大值，皆是此套件強制施行的上限，並非對 Cloudflare 平台容量的陳述。

`CloudflareRendererConfig`

算繪器設定。 final readonly。可直接建構，也可透過 CloudflareRendererConfig::fromArray() 建構。

欄位	型別	預設值	意義
`workerUrl`	`string`	—（必填）	Worker 端點 URL。必須使用 HTTPS。
`apiToken`	`string`	—（必填）	Bearer token。已標記 `#[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 pin，刻意分開保存，便於獨立驗證輪替。

isValid() 僅在 workerUrl !== '' 且 apiToken !== '' 時，才回傳 true。allPublicKeyPins() 回傳 pinnedPublicKeys 與 backupPublicKeys 去除重複後的聯集。TLS 層會接受其 SPKI 雜湊值出現在該聯集任一成員中的憑證。這符合 RFC 7469 §2.6：當所呈現的 SPKI 指紋集合與已釘選集合相交時，即驗證為已釘選連線。RFC 7469 §2.5 將備援 pin 描述為抵禦意外 pin 驗證失敗的主要復原機制。至少保留一個備援 pin，能避免憑證輪替中斷端點——請見 /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——或位於 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`

透過 S3 相容 API，將算繪後的 PDF 封存至 Cloudflare R2 的設定。 final readonly。

欄位	型別	預設值	意義
`bucketName`	`string`	—（必填）	R2 儲存桶。會依 S3 命名規則驗證。
`accountId`	`string`	—（必填）	Cloudflare 帳號 ID，用於建構預設端點。
`accessKeyId`	`string`	—（必填）	R2 access key ID。 `#[SensitiveParameter]`。
`secretAccessKey`	`string`	—（必填）	R2 secret access key。 `#[SensitiveParameter]`。
`endpoint`	`string`	`''`	自訂 S3 端點。留空時會從 `accountId` 建構預設端點。
`pathPrefix`	`string`	`'pdfs/'`	上傳物件的鍵前綴。
`maxFileSizeBytes`	`int`	`104857600`	最大上傳大小（約 100 MB），上傳前會強制檢查。

建構式會拒絕不符合 S3 相容規則的非空 bucketName。該規則為：3 至 63 個字元，小寫英數字與連字號，且以英數字開頭並結尾。違反規則會引發 InvalidArgumentException。isValid() 要求 bucketName、accountId、accessKeyId 與 secretAccessKey 皆不可為空。當 endpoint 為空時，getEndpoint() 回傳 https://<accountId>.r2.cloudflarestorage.com。

密鑰處理

apiToken、accessKeyId 與 secretAccessKey 帶有 #[SensitiveParameter] 屬性，因此 PHP 會在堆疊追蹤中遮蔽它們。請透過環境變數或密鑰管理器供應這些值。切勿將它們提交到版本控制。設定物件不可變；一旦建立，就無法在建構後再變更。

另請參閱

/integrations/cloudflare/quickstart/ — 在首次算繪中套用此設定。
/integrations/cloudflare/production-usage/ — 將回退、R2 封存與 API 防護串接在一起。
/integrations/cloudflare/security-and-operations/ — 釘選、SSRF 防禦與密鑰輪替。

NextPDF Cloudflare 橋接設定

概覽

CloudflareRendererConfig

fromArray() 鍵對應表