Bắt đầu nhanh — lần kết xuất đầu tiên trên edge

Tổng quan

Trong trang này, bạn sẽ chuyển một chuỗi Hypertext Markup Language (HTML) thành một tệp Portable Document Format (PDF). Mỗi lệnh gọi tương ứng với một phương thức; hành vi của từng phương thức được kiểm chứng trong tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php.

Điều kiện tiên quyết

• Một endpoint Worker phục vụ render contract qua Hypertext Transfer Protocol Secure (HTTPS).
• Một bearer token được Worker chấp nhận.
• Một client PHP Standards Recommendation 18 (PSR-18) và các factory PHP Standards Recommendation 17 (PSR-17) có sẵn trên đường dẫn (xem /integrations/cloudflare/install/).

Worker contract, theo quan sát từ CloudflareResponseParser: khi thành công, Worker trả về Hypertext Transfer Protocol (HTTP) 200. Phản hồi chứa hoặc Content-Type: application/pdf (các byte PDF thô) hoặc Content-Type: application/json với một trường pdf dạng base64. Bất kỳ trạng thái nào khác 200, hoặc bất kỳ phần thân nào không bắt đầu bằng marker %PDF, đều được coi là lỗi.

Bước 1 — Tạo cấu hình

<?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 lấy từ môi trường và không bao giờ được viết cứng trong mã. workerUrl phải dùng HTTPS. Nếu bạn truyền một URL http://, bridge sẽ từ chối URL đó với Worker URL must use HTTPS trước khi gửi bất kỳ yêu cầu nào.

Bước 2 — Tạo 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
);

Constructor cần bốn đối số: config, client PSR-18, request factory và stream factory. Bốn đối số còn lại là tùy chọn: logger, local-renderer factory, một chính sách bảo mật HTML rõ ràng và response factory. Việc cung cấp response factory sẽ bật transport client URL (cURL) đã ghim nếu có tập Internet Protocol (IP) đã phân giải hoặc tập pin Subject Public Key Info (SPKI) (xem /integrations/cloudflare/security-and-operations/).

Bước 3 — Kết xuất và ghi

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() mặc định dùng chiều rộng A4 (595.28 điểm PDF) và chiều cao tự dò (heightPt: 0). Hai kiểu exception được tách riêng có chủ đích. CloudflareRenderException là lỗi ở phía Worker, và lỗi này không được thử lại bằng fallback. CloudflareNotAvailableException nghĩa là không thể tiếp cận edge và không có fallback cục bộ nào khả dụng.

Bước 4 — Kiểm tra kết quả

CloudflareRenderResult là final readonly. Các trường bên dưới được điền từ header phản hồi trên đường nhị phân, hoặc từ các trường JavaScript Object Notation (JSON) trên đường JSON.

Thành viên	Nguồn
pdfData	Byte PDF thô
widthPt	Chiều rộng bạn đã yêu cầu
heightPt	X-Pdf-Height-Pt header / JSON heightPt; mặc định là 841.89 (chiều cao A4) khi vắng mặt hoặc không dương
contentHeightPx	X-Content-Height-Px / JSON contentHeightPx
renderLocation	Lấy từ phần hậu tố của header CF-Ray (đường nhị phân) hoặc JSON renderLocation
renderTimeMs	X-Render-Time-Ms / JSON renderTimeMs
size()	strlen($pdfData)
isValid()	true khi các byte bắt đầu bằng %PDF

Tùy chọn — kích thước giấy, phông chữ, CSS tùy chỉnh

$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 chỉ có ý nghĩa khi config đặt r2FontBucket. Khi đó, payload mang theo tên bucket và các đường dẫn tệp phông chữ được yêu cầu để Worker có thể tải chúng.

Tùy chọn — kiểm tra khả năng tiếp cận

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

isAvailable() gửi một HTTP HEAD đã xác thực đến URL của Worker. Phương thức này trả về true khi trạng thái dưới 500. Nó trả về false mà không ném exception khi config không hợp lệ hoặc yêu cầu thất bại. Hãy coi đây là một gợi ý, không phải một bảo đảm. Worker vẫn có thể làm thất bại lệnh POST tiếp theo.

Xem thêm

• /integrations/cloudflare/production-usage/ — đấu nối fallback, telemetry và lưu trữ R2.
• /integrations/cloudflare/troubleshooting/ — mỗi lỗi được ánh xạ tới exception và thông báo tương ứng.
• /integrations/cloudflare/configuration/ — tài liệu tham khảo đầy đủ cho các trường.