Tích hợp NextPDF với Cloudflare

Tổng quan nhanh

Trang này trình bày toàn bộ quy trình Cloudflare: cài đặt gói, cấu hình gói, kết xuất một tệp Portable Document Format (PDF) và tùy chọn lưu trữ kết quả. Mỗi bước đều chuyển tác vụ kết xuất qua một Cloudflare Worker và R2. Hãy dùng hướng dẫn thực hành này cùng với trang khái niệm /integrations/cloudflare/overview/ và trang tham chiếu /integrations/cloudflare/configuration/.

Cài đặt

composer require nextpdf/cloudflare:^0.1

Tiếp theo, hãy thêm một client PHP Standards Recommendation (PSR)-18 và các factory PSR-17, chẳng hạn như Guzzle 7. Gói này chỉ khai báo các contract PSR và không đi kèm client cụ thể nào, nên bạn cần tự cung cấp client. Để xem đầy đủ chi tiết, hãy xem /integrations/cloudflare/install/.

Khởi động/tự động phát hiện

Cầu nối này không đi kèm service provider hay bundle nào. Hãy khởi tạo trực tiếp từ các collaborator PSR và một CloudflareRendererConfig. Framework máy chủ của bạn nên đăng ký nó trong container bằng cách tái sử dụng binding PSR-18 hiện có của ứng dụng. Để xem đầy đủ trình tự khởi động và ví dụ binding container, hãy xem /integrations/cloudflare/boot-and-discovery/.

Đăng ký container

Hãy đăng ký CloudflareHtmlRenderer dưới dạng singleton. Truyền vào client PSR-18, các factory request và stream PSR-17, cùng một logger PSR-3 tùy chọn. Khi dùng transport cURL có pinning, hãy truyền thêm một factory response PSR-17. Xem ví dụ binding trong /integrations/cloudflare/boot-and-discovery/.

Xuất bản cấu hình

Gói này đọc thiết lập từ một CloudflareRendererConfig. Hãy nạp secret từ môi trường, không bao giờ từ các tệp đã commit:

<?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 phải dùng giao thức Hypertext Transfer Protocol Secure (HTTPS). apiToken được đánh dấu #[SensitiveParameter]. Để xem tham chiếu đầy đủ về các trường, hãy xem /integrations/cloudflare/configuration/, trong đó bao quát các trường pin Subject Public Key Info (SPKI) và mọi giá trị mặc định. Cấu hình lưu trữ R2 và lớp bảo vệ application programming interface (API) được trình bày trong /integrations/cloudflare/production-usage/.

Kiểm thử nhanh service provider/bundle

Không có service provider nào để kiểm thử nhanh. Thay vào đó, hãy dùng bước kiểm tra lúc khởi động này:

$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() chỉ kiểm tra tính đầy đủ và không thực hiện lệnh gọi mạng nào. isAvailable() thực hiện một lệnh HEAD có xác thực. Phương thức này trả về false mà không ném ngoại lệ khi Worker ngừng hoạt động.

Các điểm vào API công khai

Gói này cung cấp các giao diện công khai sau trong NextPDF\Cloudflare\:

Kiểu	Vai trò
`CloudflareHtmlRenderer`	Điểm vào kết xuất: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Cấu hình của trình kết xuất (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Kết quả kết xuất có kiểu (`isValid()`, `size()`).
`CloudflareRenderPayload`	Payload JavaScript Object Notation (JSON) của Worker (`toJson()`).
`CloudflareResponseParser`	Bộ phân tích phản hồi của Worker thành kết quả.
`CloudflareSecurityPolicy`	Xác thực đầu vào và URL.
`Transport\PinnedCurlTransport`	Transport PSR-18 có pinning Domain Name System (DNS) / Transport Layer Security (TLS).
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Các contract dự phòng cục bộ.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Bảo vệ API ở chiều vào.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	Lưu trữ R2.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Hệ thống phân cấp ngoại lệ.

Để xem hướng dẫn kết xuất đầy đủ theo từng bước, hãy xem /integrations/cloudflare/quickstart/. Để thiết lập cho môi trường production, hãy xem /integrations/cloudflare/production-usage/, trong đó bao quát cơ chế dự phòng, telemetry, lưu trữ và bảo vệ.

Xem thêm

/integrations/cloudflare/overview/ — ranh giới tin cậy và mô hình kết xuất ở edge.
/integrations/cloudflare/quickstart/ — lần kết xuất đầu tiên có thể chạy được.
/integrations/cloudflare/boot-and-discovery/ — chi tiết về cách kết nối container.
/integrations/cloudflare/security-and-operations/ — phòng chống server-side request forgery (SSRF), pinning và runbook vận hành.
/integrations/cloudflare/troubleshooting/ — các kiểu lỗi được ánh xạ tới ngoại lệ.