เริ่มต้นใช้งานอย่างรวดเร็ว — เรนเดอร์ที่ edge ครั้งแรก

ภาพรวมโดยย่อ

หน้านี้จะแสดงวิธีแปลงสตริง Hypertext Markup Language (HTML) หนึ่งสตริงเป็นไฟล์ Portable Document Format (PDF) หนึ่งไฟล์ การเรียกแต่ละครั้งแมปกับเมท็อดหนึ่งเมท็อด และพฤติกรรมของแต่ละเมท็อดได้รับการตรวจสอบไว้ใน tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php

สิ่งที่ต้องมีก่อน

• Worker endpoint ที่ให้บริการตาม render contract ผ่าน Hypertext Transfer Protocol Secure (HTTPS)
• bearer token ที่ Worker ยอมรับ
• ไคลเอนต์ PHP Standards Recommendation 18 (PSR-18) และแฟกทอรี PHP Standards Recommendation 17 (PSR-17) ที่พร้อมใช้งานใน path (ดู /integrations/cloudflare/install/)

Worker contract ที่เห็นได้จาก CloudflareResponseParser: เมื่อสำเร็จจะคืนค่า Hypertext Transfer Protocol (HTTP) 200 การตอบกลับจะมีอย่างใดอย่างหนึ่งคือ Content-Type: application/pdf (ไบต์ PDF ดิบ) หรือ Content-Type: application/json พร้อมฟิลด์ pdf แบบ base64 สถานะใด ๆ ที่ไม่ใช่ 200 หรือเนื้อหาใด ๆ ที่ไม่ได้ขึ้นต้นด้วยมาร์กเกอร์ %PDF จะถือว่าเป็นความล้มเหลว

ขั้นตอนที่ 1 — สร้าง configuration

<?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 มาจาก environment และไม่ได้ถูกฮาร์ดโค้ดไว้ workerUrl ต้องใช้ HTTPS หากส่ง URL แบบ http:// bridge จะปฏิเสธด้วยข้อความ Worker URL must use HTTPS ก่อนส่งคำขอใด ๆ

ขั้นตอนที่ 2 — สร้าง 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
);

คอนสตรักเตอร์ต้องการอาร์กิวเมนต์สี่ตัว คือ config, ไคลเอนต์ PSR-18, request factory และ stream factory ส่วนอาร์กิวเมนต์อีกสี่ตัวเป็นทางเลือก คือ logger, local-renderer factory, นโยบายความปลอดภัย HTML ที่ระบุชัดเจน และ response factory การระบุ response factory จะเปิดใช้งานทรานสปอร์ต client URL (cURL) แบบ pin หากมีชุด Internet Protocol (IP) ที่รีโซลฟ์แล้ว หรือมีชุด Subject Public Key Info (SPKI) pin (ดู /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 points) และความสูงที่ตรวจหาอัตโนมัติ (heightPt: 0) exception ทั้งสองชนิดถูกแยกจากกันโดยเจตนา CloudflareRenderException คือความล้มเหลวฝั่ง Worker และจะ ไม่ ลองใหม่ด้วย fallback ส่วน CloudflareNotAvailableException หมายความว่าไม่สามารถเข้าถึง edge ได้ และไม่มี fallback ในเครื่องที่ใช้งานได้

ขั้นตอนที่ 4 — ตรวจสอบผลลัพธ์

CloudflareRenderResult เป็น final readonly ฟิลด์ด้านล่างจะถูกเติมจากเฮดเดอร์ของการตอบกลับในเส้นทางไบนารี หรือจากฟิลด์ JavaScript Object Notation (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 มีผลเฉพาะเมื่อ config กำหนด r2FontBucket จากนั้น payload จะส่งชื่อ bucket และพาธไฟล์ฟอนต์ที่ร้องขอไปด้วย เพื่อให้ Worker สามารถโหลดไฟล์เหล่านั้นได้

ทางเลือก — การตรวจสอบความพร้อมใช้งาน

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

isAvailable() ส่งคำขอ HTTP HEAD ที่ผ่านการรับรองความถูกต้องไปยัง Worker URL และจะคืนค่า true เมื่อสถานะต่ำกว่า 500 หาก config ไม่ถูกต้องหรือคำขอล้มเหลว จะคืนค่า false โดยไม่ throw ให้ถือว่านี่เป็นเพียงคำใบ้ ไม่ใช่การรับประกัน เพราะ Worker ยังอาจทำให้ POST ที่ตามมาล้มเหลวได้

ดูเพิ่มเติม

• /integrations/cloudflare/production-usage/ — การต่อเชื่อม fallback, เทเลเมทรี และการเก็บถาวรด้วย R2
• /integrations/cloudflare/troubleshooting/ — กรณีความล้มเหลวทั้งหมดที่แมปกับ exception และข้อความที่เกี่ยวข้อง
• /integrations/cloudflare/configuration/ — เอกสารอ้างอิงฟิลด์ฉบับสมบูรณ์