การผสาน NextPDF กับ Cloudflare

ภาพรวมโดยสรุป

หน้านี้แสดงเวิร์กโฟลว์ทั้งหมดสำหรับการทำงานกับ Cloudflare ตั้งแต่ติดตั้งแพ็กเกจ กำหนดค่า เรนเดอร์ไฟล์ Portable Document Format (PDF) ไปจนถึงจัดเก็บผลลัพธ์ในคลังเอกสารเมื่อต้องการ ทุกขั้นตอนส่งงานเรนเดอร์ผ่าน Cloudflare Worker และ R2 ให้ใช้คู่มือเชิงปฏิบัตินี้ควบคู่กับเอกสารเชิงแนวคิด /integrations/cloudflare/overview/ และเอกสารอ้างอิง /integrations/cloudflare/configuration/

การติดตั้ง

composer require nextpdf/cloudflare:^0.1

จากนั้นเพิ่มไคลเอนต์ PHP Standards Recommendation (PSR)-18 และแฟกทอรี PSR-17 เช่น Guzzle 7 แพ็กเกจนี้ประกาศเฉพาะสัญญา PSR และไม่ได้รวม implementation ของไคลเอนต์จริงไว้ ดังนั้นคุณต้องจัดเตรียมไคลเอนต์เอง ดูรายละเอียดทั้งหมดได้ที่ /integrations/cloudflare/install/

การบูต/การค้นพบอัตโนมัติ

บริดจ์นี้ไม่ได้รวม service provider และ bundle ใด ๆ ไว้ ให้สร้างบริดจ์โดยตรงจากองค์ประกอบ PSR ที่ใช้ร่วมกันและ CloudflareRendererConfig เฟรมเวิร์กโฮสต์ของคุณควรผูกบริดจ์นี้ไว้ในคอนเทนเนอร์ โดยนำการผูก PSR-18 ที่แอปพลิเคชันมีอยู่แล้วกลับมาใช้ซ้ำ ดูลำดับการบูตทั้งหมดและตัวอย่างการผูกคอนเทนเนอร์ได้ที่ /integrations/cloudflare/boot-and-discovery/

การผูกคอนเทนเนอร์

ผูก CloudflareHtmlRenderer เป็น singleton โดยส่งไคลเอนต์ PSR-18 แฟกทอรีคำขอและสตรีม PSR-17 และตัวบันทึกล็อก PSR-3 หากต้องการ เมื่อคุณใช้ทรานสปอร์ต cURL แบบ pinned ให้ส่งแฟกทอรีการตอบกลับ PSR-17 ด้วย ดูตัวอย่างการผูกได้ที่ /integrations/cloudflare/boot-and-discovery/

การเผยแพร่การกำหนดค่า

แพ็กเกจอ่านการตั้งค่าจาก CloudflareRendererConfig ให้โหลดข้อมูลลับจาก environment เท่านั้น อย่าโหลดจากไฟล์ที่คอมมิตไว้:

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => getenv('CF_WORKER_URL') ?: '',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => getenv('CF_R2_FONT_BUCKET') ?: null,
]);

workerUrl ต้องใช้สกีม Hypertext Transfer Protocol Secure (HTTPS) apiToken เป็น #[SensitiveParameter] ดูเอกสารอ้างอิงสำหรับฟิลด์ทั้งหมดได้ที่ /integrations/cloudflare/configuration/ ซึ่งครอบคลุมฟิลด์พิน Subject Public Key Info (SPKI) และค่าเริ่มต้นทุกค่า การกำหนดค่าการจัดเก็บคลังเอกสาร R2 และชั้นการป้องกัน application programming interface (API) อธิบายไว้ใน /integrations/cloudflare/production-usage/

การทดสอบเบื้องต้นของ service provider/bundle

ไม่มี service provider สำหรับทดสอบเบื้องต้น ให้ใช้การตรวจสอบระหว่างบูตนี้แทน:

$config = CloudflareRendererConfig::fromArray($appConfig['cloudflare']);
assert($config->isValid(), 'Cloudflare config incomplete');

// Optional runtime reachability check (authenticated HTTP HEAD):
if (!$renderer->isAvailable()) {
    // Worker not reachable — degrade or alert.
}

isValid() เป็นการตรวจสอบความครบถ้วนเท่านั้นและไม่เรียกเครือข่าย isAvailable() ทำคำขอ HEAD แบบมีการรับรองตัวตน เมธอดนี้คืนค่า false โดยไม่โยนข้อยกเว้นเมื่อ Worker หยุดทำงาน

จุดเข้าใช้งานของ public API

แพ็กเกจเปิดเผย API สาธารณะต่อไปนี้ภายใต้ NextPDF\Cloudflare\:

ชนิด	บทบาท
CloudflareHtmlRenderer	จุดเข้าใช้งานสำหรับการเรนเดอร์: render(), isAvailable(), getHtmlSecurityPolicy()
CloudflareRendererConfig	การกำหนดค่าตัวเรนเดอร์ (fromArray(), isValid(), allPublicKeyPins())
CloudflareRenderResult	ผลลัพธ์การเรนเดอร์แบบมีชนิดข้อมูล (isValid(), size())
CloudflareRenderPayload	เพย์โหลด JavaScript Object Notation (JSON) ของ Worker (toJson())
CloudflareResponseParser	ตัวแยกวิเคราะห์การตอบกลับของ Worker → ผลลัพธ์
CloudflareSecurityPolicy	การตรวจสอบความถูกต้องของอินพุตและ URL
Transport\PinnedCurlTransport	ทรานสปอร์ต PSR-18 ที่ pin ทั้ง Domain Name System (DNS) และ Transport Layer Security (TLS)
Contract\LocalRendererFactoryInterface, Contract\LocalRendererInterface	สัญญาสำหรับการสำรองในเครื่อง
ApiProtection, ApiProtectionConfig, ApiProtectionResult, ApiKeyValidator	การป้องกัน API ขาเข้า
R2ArchiveManager, R2ArchiveConfig, R2ObjectKey, R2UploadResult	การจัดเก็บคลังเอกสาร R2
Exception\CloudflareRenderException, Exception\CloudflareNotAvailableException, Exception\InvalidSpkiPinException	ลำดับชั้นของข้อยกเว้น

ดูคำแนะนำการเรนเดอร์แบบครบถ้วนได้ที่ /integrations/cloudflare/quickstart/ สำหรับการเชื่อมต่อในระบบโปรดักชัน ดูได้ที่ /integrations/cloudflare/production-usage/ ซึ่งครอบคลุมการสำรอง การวัดและส่งข้อมูลการทำงาน การจัดเก็บคลังเอกสาร และการป้องกัน

ดูเพิ่มเติม

• /integrations/cloudflare/overview/ — ขอบเขตความเชื่อถือและรูปแบบการเรนเดอร์ที่ edge
• /integrations/cloudflare/quickstart/ — การเรนเดอร์ครั้งแรกที่รันได้จริง
• /integrations/cloudflare/boot-and-discovery/ — รายละเอียดการเชื่อมต่อคอนเทนเนอร์
• /integrations/cloudflare/security-and-operations/ — การป้องกัน server-side request forgery (SSRF) การ pin และ runbook สำหรับการปฏิบัติงาน
• /integrations/cloudflare/troubleshooting/ — รูปแบบความล้มเหลวที่จับคู่กับข้อยกเว้น