Cloudflare — Edge 渲染套件¶
NextPDF Cloudflare
nextpdf/cloudflare 讓 NextPDF Core 在 Cloudflare Workers 的無狀態邊緣執行環境中生成 PDF。套件針對 Workers 的單一執行緒、無檔案系統、無 FFI 等限制進行了完整適配：使用 DocumentFactory::create() 無狀態模式、以記憶體 buffer 取代磁碟 I/O、透過 PSR-18 HTTP 客戶端與 Cloudflare R2 互動。
PHP Compatibility
This example uses PHP 8.5 syntax. If your environment runs PHP 8.1 or 7.4, use NextPDF Backport for a backward-compatible build.
核心能力¶
| 子系統 | 功能 |
|---|---|
| EdgeRenderer | Workers 環境中的無狀態 PDF 生成、fallback 策略 |
| R2Archival | PDF 封存至 R2 物件儲存、AWS Signature V4 認證 |
| PresignedUrl | 預簽名下載 URL 生成（時效性存取） |
| ApiProtection | API 金鑰驗證、KV-based 速率限制 |
Workers 環境限制¶
在 Cloudflare Workers 中執行 PHP（透過 Workers PHP Runtime 或 WasmEdge）時，以下限制須納入設計：
| 限制 | 說明 | NextPDF 因應方式 |
|---|---|---|
| 無持久化檔案系統 | 每次請求從零開始 | 所有 I/O 以記憶體 buffer 進行 |
| CPU 時間上限 50ms（免費）/ 30s（付費） | 計算密集任務受限 | Spectrum 加速器 + 輕量文件設計 |
| 記憶體上限 128MB | 大型 PDF 受限 | 串流生成、分頁輸出 |
| 無 FFI / 系統呼叫 | Spectrum Rust 加速器不可用 | 自動降級至純 PHP 實作 |
| 無 TCP socket | 只可使用 fetch() API | PSR-18 over HTTP/HTTPS |
安裝¶
快速開始¶
<?php
declare(strict_types=1);
use NextPDF\Cloudflare\EdgeRenderer;
use NextPDF\Cloudflare\Config\EdgeRendererConfig;
use NextPDF\Core\Document;
$renderer = EdgeRenderer::create(
config: EdgeRendererConfig::create(
fallbackOnTimeout: true, // CPU 超時時改用輕量模板
maxCpuMs: 20000, // 目標 CPU 時間上限（ms）
),
);
$pdfBytes = $renderer->render(function (Document $doc): void {
$doc->addPage();
$doc->text('Edge-generated PDF', x: 20, y: 30);
});
架構：Edge-first 設計¶
Cloudflare Worker (HTTP Request)
├─▶ ApiProtection::verify() — API 金鑰 + 速率限制 (KV)
│
├─▶ EdgeRenderer::render() — 無狀態 PDF 生成
│ └─▶ DocumentFactory::create() (無 Process 共享)
│
└─▶ R2Archival::store() — 非同步封存至 R2
└─▶ PresignedUrl::generate() — 時效性下載 URL