การกำหนดค่าบริดจ์ NextPDF Cloudflare

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

อ็อบเจกต์การกำหนดค่าแบบไม่เปลี่ยนรูปสามรายการควบคุมแพ็กเกจนี้ ค่าเริ่มต้นทุกค่าในหน้านี้อ่านจากลายเซ็นตัวสร้างที่เกี่ยวข้องใน src/Cloudflare/ ค่าเหล่านี้ไม่ได้อ่านจากข้อกำหนดหรือการประมาณการ เมื่อหน้านี้ระบุค่าสูงสุด ค่านั้นคือขีดจำกัด ที่แพ็กเกจนี้บังคับใช้ และไม่ใช่คำกล่าวเกี่ยวกับความจุของแพลตฟอร์ม Cloudflare

CloudflareRendererConfig

การกำหนดค่าตัวเรนเดอร์แบบ final readonly สร้างอ็อบเจกต์โดยตรงหรือผ่าน CloudflareRendererConfig::fromArray()

ฟิลด์	ชนิด	ค่าเริ่มต้น	ความหมาย
workerUrl	string	— (จำเป็น)	URL จุดสิ้นสุดของ Worker ต้องเป็น HTTPS
apiToken	string	— (จำเป็น)	โทเค็น Bearer ที่ทำเครื่องหมายด้วย #[SensitiveParameter]
renderTimeout	int	30	ระยะหมดเวลาการถ่ายโอนเป็นวินาที ใช้โดยแทรนสปอร์ต cURL ที่ปักหมุดไว้
defaultCss	string	''	CSS ที่ฉีดเข้าไปในเพย์โหลดก่อน HTML ของคุณ
maxHtmlSize	int	5000000	ขนาดอินพุต HTML สูงสุดเป็นไบต์ บังคับใช้ก่อนส่งคำขอ
r2FontBucket	?string	null	ชื่อบักเก็ต R2 สำหรับแพ็กเกจฟอนต์แบบกำหนดเอง
fallbackToLocal	bool	true	ระบุว่า Worker ที่ติดต่อไม่ได้จะถอยกลับไปใช้ตัวเรนเดอร์ภายในเครื่องหรือไม่
pinnedPublicKeys	list<string>	[]	ลายนิ้วมือ SPKI แบบ SHA-256 ในรูปแบบ sha256/<base64>
backupPublicKeys	list<string>	[]	พิน SPKI สำรอง เก็บแยกไว้ต่างหากเพื่อให้ตรวจสอบความถูกต้องของการหมุนเวียนได้อย่างเป็นอิสระ

isValid() จะคืนค่า true เฉพาะเมื่อ workerUrl !== '' และ apiToken !== '' allPublicKeyPins() จะคืนค่ายูเนียนของ pinnedPublicKeys และ backupPublicKeys หลังตัดรายการซ้ำออกแล้ว ชั้น TLS จะยอมรับใบรับรองที่มีค่าแฮช SPKI ปรากฏอยู่ในสมาชิกใดก็ตามของยูเนียนนั้น พฤติกรรมนี้สอดคล้องกับ RFC 7469 §2.6 ซึ่งตรวจสอบความถูกต้องของการเชื่อมต่อที่ปักหมุดไว้เมื่อชุดลายนิ้วมือ SPKI ที่นำเสนอมีส่วนตัดกับชุดที่ปักหมุดไว้ RFC 7469 §2.5 อธิบายว่าพินสำรองเป็นกลไกการกู้คืนหลักเมื่อการตรวจสอบพินล้มเหลวโดยไม่ตั้งใจ เก็บพินสำรองไว้อย่างน้อยหนึ่งพินเพื่อไม่ให้การหมุนเวียนใบรับรองทำให้จุดสิ้นสุดใช้งานไม่ได้ — ดู /integrations/cloudflare/security-and-operations/

fromArray() แผนผังคีย์

CloudflareRendererConfig::fromArray() อ่านคีย์แบบ snake_case และใช้ค่าเริ่มต้นเดียวกันเมื่อไม่มีคีย์หรือชนิดไม่ถูกต้อง:

คีย์อาร์เรย์	แมปไปยัง
worker_url	workerUrl
api_token	apiToken
render_timeout	renderTimeout (ค่าเริ่มต้น 30)
default_css	defaultCss
max_html_size	maxHtmlSize (ค่าเริ่มต้น 5000000)
r2_font_bucket	r2FontBucket
fallback_to_local	fallbackToLocal (ค่าเริ่มต้น true)
pinned_public_keys	pinnedPublicKeys (สมาชิกที่ไม่ใช่สตริงจะถูกตัดออก)
backup_public_keys	backupPublicKeys (สมาชิกที่ไม่ใช่สตริงจะถูกตัดออก)

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => 'https://pdf-renderer.example.workers.dev/render',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => 'pdf-fonts',
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

ขีดจำกัดขนาดอินพุตที่แพ็กเกจบังคับใช้

ขีดจำกัดเหล่านี้ถูกบังคับใช้โดย CloudflareSecurityPolicy::validate() ก่อนที่คำขอใดๆ จะออกจากกระบวนการ ตัวเลขเหล่านี้อ่านจากซอร์ส:

ขีดจำกัด	ค่า	ตำแหน่ง
อินพุต HTML สูงสุด	maxHtmlSize (ค่าเริ่มต้น 5000000 ไบต์)	CloudflareSecurityPolicy::validate()
ขนาดสูงสุดของ data-URI แบบ base64 หลังถอดรหัส	13631488 ไบต์ (≈13 MB)	CloudflareSecurityPolicy::MAX_DATA_URI_BYTES

หากเกินค่าใดค่าหนึ่ง ระบบจะโยน RuntimeException พร้อมข้อความที่ระบุขนาดที่เกินและขีดจำกัด เพดาน base64 มีไว้เพื่อป้องกันการขยายตัวอย่างมากจากการคลายการบีบอัด นโยบายจะประมาณขนาดหลังถอดรหัสจากความยาวของ base64 และปฏิเสธเมื่อขนาดถึงหรือเกินเพดาน แท็ก <meta http-equiv="refresh"> ก็ถูกปฏิเสธเช่นกันโดยไม่คำนึงถึงตัวพิมพ์เล็กใหญ่ เพราะแท็กนี้สามารถสั่งเปลี่ยนเส้นทางจากภายในหน้าที่เรนเดอร์ได้

แพ็กเกจระบุเฉพาะขีดจำกัดที่ตัวแพ็กเกจเองบังคับใช้ แพ็กเกจไม่ได้ กล่าวอ้างใดๆ เกี่ยวกับเพดานคำขอ CPU หรือหน่วยความจำของ Worker เอง โปรดดู เอกสารทางการของ Cloudflare และการนำ Worker ของคุณไปใช้สำหรับ ค่าเหล่านั้น

ApiProtectionConfig

การกำหนดค่าสำหรับชั้นการป้องกันคำขอแบบเลือกใช้ได้ ซึ่ง Worker — หรือเกตเวย์ PHP ที่อยู่หน้า Worker — ใช้กับคำขอเรนเดอร์ขาเข้า แบบ final readonly

ฟิลด์	ชนิด	ค่าเริ่มต้น	ความหมาย
maxRequestsPerMinute	int	60	เพดานคำขอต่อไคลเอนต์ต่อนาที
maxRequestsPerHour	int	1000	เพดานคำขอต่อไคลเอนต์ต่อชั่วโมง
maxPayloadSizeBytes	int	10485760	เพย์โหลดขาเข้าสูงสุด (≈10 MB)
allowedOrigins	list<string>	[]	รายการอนุญาตสำหรับ CORS ค่าว่างหมายความว่าที่นี่ไม่ได้ระบุข้อจำกัด origin
requireApiKey	bool	true	ระบุว่าต้องใช้คีย์ API หรือไม่
apiKeyHeader	string	'X-Api-Key'	ส่วนหัวที่ใช้ส่งคีย์ API
rateLimitWindowSeconds	int	60	ความยาวของหน้าต่างรายนาที เป็นวินาที

fromArray() อ่าน max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header และ rate_limit_window_seconds isValid() กำหนดให้ฟิลด์ตัวเลขทุกฟิลด์ต้องเป็นค่าบวก และ apiKeyHeader ต้องไม่เป็นค่าว่าง

R2ArchiveConfig

การกำหนดค่าสำหรับเก็บถาวร PDF ที่เรนเดอร์แล้วไปยัง Cloudflare R2 ผ่าน API ที่เข้ากันได้กับ S3 แบบ final readonly

ฟิลด์	ชนิด	ค่าเริ่มต้น	ความหมาย
bucketName	string	— (จำเป็น)	บักเก็ต R2 ตรวจสอบความถูกต้องตามกฎการตั้งชื่อของ S3
accountId	string	— (จำเป็น)	รหัสบัญชี Cloudflare ใช้สร้างจุดสิ้นสุดเริ่มต้น
accessKeyId	string	— (จำเป็น)	รหัสคีย์การเข้าถึง R2 ที่ทำเครื่องหมายด้วย #[SensitiveParameter]
secretAccessKey	string	— (จำเป็น)	คีย์การเข้าถึงลับของ R2 ที่ทำเครื่องหมายด้วย #[SensitiveParameter]
endpoint	string	''	จุดสิ้นสุด S3 แบบกำหนดเอง ค่าว่างจะสร้างจุดสิ้นสุดเริ่มต้นจาก accountId
pathPrefix	string	'pdfs/'	คำนำหน้าคีย์สำหรับอ็อบเจกต์ที่อัปโหลด
maxFileSizeBytes	int	104857600	ขนาดอัปโหลดสูงสุด (≈100 MB) บังคับใช้ก่อนอัปโหลด

ตัวสร้างจะปฏิเสธ bucketName ที่ไม่เป็นค่าว่างซึ่งไม่ตรงตามกฎที่เข้ากันได้กับ S3 กฎดังกล่าวคือ: ความยาว 3–63 อักขระ เป็นตัวอักษรและตัวเลขพิมพ์เล็กหรือเครื่องหมายยัติภังค์ โดยขึ้นต้นและลงท้ายด้วยตัวอักษรหรือตัวเลข การละเมิดจะทำให้เกิด InvalidArgumentException isValid() กำหนดให้ bucketName, accountId, accessKeyId และ secretAccessKey ต้องไม่เป็นค่าว่าง เมื่อ endpoint เป็นค่าว่าง getEndpoint() จะคืนค่า https://<accountId>.r2.cloudflarestorage.com

การจัดการความลับ

apiToken, accessKeyId และ secretAccessKey มีแอตทริบิวต์ #[SensitiveParameter] ดังนั้น PHP จะตัดค่าเหล่านี้ออกจาก stack trace รับค่าเหล่านี้จากตัวแปรสภาพแวดล้อมหรือตัวจัดการความลับ ห้ามคอมมิตค่าเหล่านี้ อ็อบเจกต์การกำหนดค่าเป็นแบบไม่เปลี่ยนรูป ดังนั้นค่าที่ตั้งไว้แล้วจึงไม่สามารถเปลี่ยนแปลงได้หลังการสร้าง

ดูเพิ่มเติม

• /integrations/cloudflare/quickstart/ — นำการกำหนดค่านี้ไปใช้ในการเรนเดอร์ครั้งแรก
• /integrations/cloudflare/production-usage/ — การเชื่อมต่อการถอยกลับ การเก็บถาวรบน R2 และการป้องกัน API เข้าด้วยกัน
• /integrations/cloudflare/security-and-operations/ — การปักหมุด การป้องกัน SSRF และการหมุนเวียนความลับ