Mulai cepat — render edge pertama Anda

Sekilas

Di halaman ini, Anda mengubah satu string Hypertext Markup Language (HTML) menjadi berkas Portable Document Format (PDF). Setiap pemanggilan dipetakan ke satu metode, dan perilaku tiap metode diverifikasi di tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php.

Prasyarat

• Endpoint Worker yang mengekspos kontrak render melalui Hypertext Transfer Protocol Secure (HTTPS).
• Bearer token yang diterima oleh Worker.
• Klien PHP Standards Recommendation 18 (PSR-18) dan factory PHP Standards Recommendation 17 (PSR-17) yang tersedia di path (lihat /integrations/cloudflare/install/).

Berdasarkan CloudflareResponseParser, kontrak Worker adalah sebagai berikut: saat berhasil, Worker mengembalikan Hypertext Transfer Protocol (HTTP) 200. Respons berisi salah satu dari Content-Type: application/pdf (byte PDF mentah) atau Content-Type: application/json dengan field pdf base64. Status apa pun selain 200, atau body apa pun yang tidak diawali penanda %PDF, dianggap sebagai kegagalan.

Langkah 1 — Susun konfigurasi

<?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 diambil dari environment dan tidak pernah di-hard-code. workerUrl harus menggunakan HTTPS. Jika Anda memberikan URL http://, bridge akan menolaknya dengan Worker URL must use HTTPS sebelum mengirim permintaan apa pun.

Langkah 2 — Bangun renderer

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
);

Konstruktor membutuhkan empat argumen: config, klien PSR-18, request factory, dan stream factory. Empat argumen lainnya bersifat opsional: logger, factory local-renderer, kebijakan keamanan HTML eksplisit, dan response factory. Menyediakan response factory mengaktifkan transport Client URL (cURL) yang dipasangkan (pinned) jika tersedia set Internet Protocol (IP) yang telah di-resolve atau set pin Subject Public Key Info (SPKI) (lihat /integrations/cloudflare/security-and-operations/).

Langkah 3 — Render dan tulis

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() secara default menggunakan lebar A4 (595.28 poin PDF) dan tinggi yang dideteksi otomatis (heightPt: 0). Kedua tipe exception ini sengaja dipisahkan. CloudflareRenderException adalah kegagalan di sisi Worker, dan kegagalan ini tidak dicoba ulang dengan fallback. CloudflareNotAvailableException berarti edge tidak dapat dijangkau dan tidak ada fallback lokal yang tersedia.

Langkah 4 — Periksa hasilnya

CloudflareRenderResult bersifat final readonly. Field-field di bawah ini diisi dari header respons pada jalur biner atau dari field JavaScript Object Notation (JSON) pada jalur JSON.

Member	Sumber
pdfData	Byte PDF mentah
widthPt	Lebar yang Anda minta
heightPt	Header X-Pdf-Height-Pt / JSON heightPt; secara default menjadi 841.89 (tinggi A4) jika tidak ada atau nilainya tidak positif
contentHeightPx	X-Content-Height-Px / JSON contentHeightPx
renderLocation	Diturunkan dari sufiks header CF-Ray (jalur biner) atau JSON renderLocation
renderTimeMs	X-Render-Time-Ms / JSON renderTimeMs
size()	strlen($pdfData)
isValid()	true jika byte diawali dengan %PDF

Opsional — ukuran kertas, font, dan CSS kustom

$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 hanya berpengaruh ketika config menyetel r2FontBucket. Payload kemudian membawa nama bucket dan path berkas font yang diminta agar Worker dapat memuatnya.

Opsional — uji keterjangkauan

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

isAvailable() mengirim HTTP HEAD yang terautentikasi ke URL Worker. Method ini mengembalikan true ketika status di bawah 500. Method ini mengembalikan false tanpa melempar exception ketika config tidak valid atau permintaan gagal. Perlakukan ini sebagai petunjuk, bukan jaminan. Worker tetap dapat menggagalkan POST berikutnya.

Lihat juga

• /integrations/cloudflare/production-usage/ — wiring fallback, telemetri, dan pengarsipan R2.
• /integrations/cloudflare/troubleshooting/ — setiap kegagalan dipetakan ke exception beserta pesannya.
• /integrations/cloudflare/configuration/ — referensi field lengkap.