快速上手 — 第一次邊緣渲染

概覽

本頁會帶你將一段 HTML 字串轉換成 PDF 檔案。這裡看到的每個呼叫都對應到一個方法；每個方法的行為也都已在 tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php 中驗證。

先決條件

一個透過 HTTPS 提供渲染合約的 Worker 端點。
一個 Worker 接受的 bearer token。
載入路徑上要有一個 PSR-18 用戶端與 PSR-17 工廠（請參閱 /integrations/cloudflare/install/）。

從 CloudflareResponseParser 觀察到的 Worker 合約如下：成功時會回傳 HTTP 200。回應會帶有 Content-Type: application/pdf（原始 PDF 位元組）或 Content-Type: application/json（含有 base64 編碼的 pdf 欄位）。任何非 200 的狀態，或開頭並非 %PDF 標記的內文，都會被視為失敗。

步驟 1 — 建立設定

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = new CloudflareRendererConfig(
    workerUrl: 'https://pdf-renderer.example.workers.dev/render',
    apiToken: getenv('CF_PDF_TOKEN') ?: throw new RuntimeException('CF_PDF_TOKEN not set'),
);

token 會從環境讀取，絕不寫死在程式碼中。workerUrl 必須使用 HTTPS。如果你傳入 http:// URL，橋接層會在送出任何請求之前，以 Worker URL must use HTTPS 拒絕該 URL。

步驟 2 — 建立渲染器

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use NextPDF\Cloudflare\CloudflareHtmlRenderer;

$httpFactory = new HttpFactory();

$renderer = new CloudflareHtmlRenderer(
    config:          $config,
    httpClient:      new Client(),     // PSR-18 ClientInterface
    requestFactory:  $httpFactory,     // PSR-17 RequestFactoryInterface
    streamFactory:   $httpFactory,     // PSR-17 StreamFactoryInterface
    logger:          null,             // optional PSR-3 LoggerInterface
    responseFactory: $httpFactory,     // PSR-17; enables the pinned transport
);

建構式需要四個引數：設定、PSR-18 用戶端、request 工廠，以及 stream 工廠。另有四個選用引數：logger、本機渲染器工廠、明確的 HTML 安全性原則，以及 response 工廠。當你提供 response 工廠時，只要存在已解析的 IP 集合或 SPKI pin 集合，就會啟用已釘選（pinned）的 cURL 傳輸（請參閱 /integrations/cloudflare/security-and-operations/）。

步驟 3 — 渲染並寫出

use NextPDF\Cloudflare\Exception\CloudflareNotAvailableException;
use NextPDF\Cloudflare\Exception\CloudflareRenderException;

try {
    $result = $renderer->render('<h1>Hello from the edge</h1>');

    if (!$result->isValid()) {
        throw new RuntimeException('Worker did not return a valid PDF');
    }

    file_put_contents('output.pdf', $result->pdfData);
    printf("Wrote %d bytes from edge %s in %.1f ms\n",
        $result->size(),
        $result->renderLocation !== '' ? $result->renderLocation : 'unknown',
        $result->renderTimeMs,
    );
} catch (CloudflareRenderException $e) {
    // Worker answered but the render failed (HTTP error or malformed body).
    fwrite(STDERR, 'Render failed: ' . $e->getMessage() . PHP_EOL);
    exit(1);
} catch (CloudflareNotAvailableException $e) {
    // Worker unreachable and no usable fallback.
    fwrite(STDERR, 'Edge unavailable: ' . $e->getMessage() . PHP_EOL);
    exit(2);
}

render() 預設使用 A4 寬度（595.28 PDF 點），並自動偵測高度（heightPt: 0）。這兩種例外型別是刻意區分的。CloudflareRenderException 代表 Worker 端失敗，而且不會以備援機制重試。CloudflareNotAvailableException 表示無法連到邊緣，且沒有可用的本機備援。

步驟 4 — 檢視結果

CloudflareRenderResult 是 final readonly。下列欄位在二進位路徑上由回應標頭填入；在 JSON 路徑上則由 JSON 欄位填入。

成員	來源
`pdfData`	原始 PDF 位元組
`widthPt`	你要求的寬度
`heightPt`	`X-Pdf-Height-Pt` 標頭 / JSON `heightPt`；當缺漏或非正值時，預設為 `841.89`（A4 高度）
`contentHeightPx`	`X-Content-Height-Px` / JSON `contentHeightPx`
`renderLocation`	由 `CF-Ray` 標頭後綴（二進位路徑）或 JSON `renderLocation` 衍生而來
`renderTimeMs`	`X-Render-Time-Ms` / JSON `renderTimeMs`
`size()`	`strlen($pdfData)`
`isValid()`	`true`：當位元組以 `%PDF` 開頭時

選用 — 自訂紙張尺寸、字型、CSS

$result = $renderer->render(
    html:     '<div style="font-family: NotoSansCJK;">繁體中文文件</div>',
    widthPt:  595.28,
    heightPt: 841.89,           // explicit A4; 0 lets the Worker auto-detect
    fontFiles: ['NotoSansCJKtc-Regular.ttf'],
);

fontFiles 只有在設定了 r2FontBucket 時才有意義。如此一來，酬載便會帶有 bucket 名稱與要求的字型檔路徑，讓 Worker 能夠載入它們。

選用 — 可連線性探測

if ($renderer->isAvailable()) {
    $result = $renderer->render($html);
}

isAvailable() 會向 Worker URL 送出一個帶驗證的 HTTP HEAD。只要狀態低於 500，它就會回傳 true。當設定無效或請求失敗時，它會回傳 false 而不會拋出例外。請把它當成提示，而非保證；Worker 在後續的 POST 仍可能失敗。

另請參閱

/integrations/cloudflare/production-usage/ — 備援接線、遙測、R2 封存。
/integrations/cloudflare/troubleshooting/ — 各種失敗對應的例外與訊息。
/integrations/cloudflare/configuration/ — 完整的欄位參考。