クイックスタート — はじめてのエッジレンダリング

概要

このページでは、1 つの HTML 文字列を PDF ファイルへ変換します。ここで示すすべての呼び出しは実際のメソッドに対応しており、各メソッドの動作は tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php で検証されています。

前提条件

レンダリングコントラクトを HTTPS 経由で提供している Worker エンドポイント。
Worker に受け入れられるベアラートークン。
パス上にある PSR-18 クライアントと PSR-17 ファクトリ（/integrations/cloudflare/install/ を参照）。

CloudflareResponseParser で確認できる Worker コントラクトでは、成功時に HTTP 200 を返します。レスポンスとして返されるのは、Content-Type: application/pdf（生の PDF バイト列）か、base64 の pdf フィールドを持つ Content-Type: application/json のいずれかです。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'),
);

トークンは環境変数から読み取り、ハードコードしません。workerUrl は HTTPS である必要があります。http:// の URL を渡すと、ブリッジはリクエスト送信前に Worker URL must use HTTPS として拒否します。

ステップ 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 クライアント、リクエストファクトリ、ストリームファクトリの 4 つが必須です。加えて、ロガー、ローカルレンダラーファクトリ、明示的な HTML セキュリティポリシー、レスポンスファクトリの 4 つは省略可能です。レスポンスファクトリを指定すると、解決済みの IP セットまたは SPKI ピンセットが存在する場合に、ピン留めされた 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）を使用します。2 つの例外型は意図的に区別されています。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()`	バイト列が `%PDF` で始まる場合は `true`

オプション — カスタム用紙サイズ、フォント、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 が指定されている場合にのみ有効です。その場合、ペイロードにはバケット名と要求されたフォントファイルのパスが含まれるため、Worker はそれらを読み込めます。

オプション — 到達性プローブ

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

isAvailable() は、認証付きの HTTP HEAD リクエストを Worker URL に送信します。ステータスが 500 未満の場合は true を返します。設定が無効な場合やリクエストが失敗した場合は、例外を投げずに false を返します。これは保証ではなく、ヒントとして扱ってください。それでも Worker は後続の POST で失敗する可能性があります。