Szybki start — pierwsze renderowanie na brzegu sieci

W skrócie

Na tej stronie przekształcisz pojedynczy ciąg znaków Hypertext Markup Language (HTML) w plik Portable Document Format (PDF). Każde wywołanie odpowiada jednej metodzie, a zachowanie każdej z nich jest weryfikowane w pliku tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php.

Wymagania wstępne

Punkt końcowy Worker udostępniający kontrakt renderowania przez Hypertext Transfer Protocol Secure (HTTPS).
Token bearer akceptowany przez Worker.
Klient PHP Standards Recommendation 18 (PSR-18) oraz fabryki PHP Standards Recommendation 17 (PSR-17) dostępne na ścieżce (zob. /integrations/cloudflare/install/).

Kontrakt Worker z perspektywy CloudflareResponseParser: powodzenie oznacza Hypertext Transfer Protocol (HTTP) 200. Odpowiedź zawiera albo Content-Type: application/pdf (surowe bajty PDF), albo Content-Type: application/json z polem pdf zakodowanym w base64. Status inny niż 200 oraz ciało odpowiedzi, które nie zaczyna się od znacznika %PDF, są traktowane jako błąd.

Krok 1 — Utwórz konfigurację

<?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 jest pobierany ze środowiska i nigdy nie trafia na stałe do kodu. workerUrl musi używać protokołu HTTPS. Jeśli przekażesz adres URL z http://, most odrzuci go z komunikatem Worker URL must use HTTPS, zanim wyśle jakiekolwiek żądanie.

Krok 2 — Zbuduj 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
);

Konstruktor wymaga czterech argumentów: konfiguracji, klienta PSR-18, fabryki żądań oraz fabryki strumieni. Kolejne cztery argumenty są opcjonalne: rejestrator zdarzeń, fabryka lokalnego renderera, jawna polityka bezpieczeństwa HTML oraz fabryka odpowiedzi. Przekazanie fabryki odpowiedzi włącza przypięty transport cURL, jeśli dostępny jest rozwiązany zestaw adresów Internet Protocol (IP) albo zestaw przypięć Subject Public Key Info (SPKI) (zob. /integrations/cloudflare/security-and-operations/).

Krok 3 — Renderuj i zapisz

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);
}

Domyślnie render() przyjmuje szerokość A4 (595.28 punktów PDF) oraz automatycznie wykrytą wysokość (heightPt: 0). Te dwa typy wyjątków są celowo rozróżnione. CloudflareRenderException oznacza błąd po stronie Worker i nie powoduje ponowienia z użyciem mechanizmu zastępczego. CloudflareNotAvailableException oznacza, że nie udało się połączyć z brzegiem sieci i nie był dostępny żaden lokalny mechanizm zastępczy.

Krok 4 — Sprawdź wynik

CloudflareRenderResult to klasa final readonly. Poniższe pola są wypełniane z nagłówków odpowiedzi dla ścieżki binarnej albo z pól JavaScript Object Notation (JSON) dla ścieżki JSON.

Składowa	Źródło
`pdfData`	Surowe bajty PDF
`widthPt`	Żądana szerokość
`heightPt`	Nagłówek `X-Pdf-Height-Pt` / JSON `heightPt`; domyślnie `841.89` (wysokość A4), gdy brakuje wartości lub jest ona niedodatnia
`contentHeightPx`	`X-Content-Height-Px` / JSON `contentHeightPx`
`renderLocation`	Ustalane na podstawie sufiksu nagłówka `CF-Ray` (ścieżka binarna) lub z JSON `renderLocation`
`renderTimeMs`	`X-Render-Time-Ms` / JSON `renderTimeMs`
`size()`	`strlen($pdfData)`
`isValid()`	`true`, gdy bajty zaczynają się od `%PDF`

Opcjonalnie — niestandardowy rozmiar papieru, czcionki, 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 jest brane pod uwagę tylko wtedy, gdy konfiguracja ustawia r2FontBucket. Ładunek zawiera wtedy nazwę zasobnika oraz żądane ścieżki plików czcionek, aby Worker mógł je załadować.

Opcjonalnie — sonda dostępności

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

isAvailable() wysyła uwierzytelnione żądanie HTTP HEAD na adres URL Worker. Zwraca true, jeśli status jest niższy niż 500. Zwraca false bez zgłaszania wyjątku, jeśli konfiguracja jest nieprawidłowa lub żądanie zakończy się niepowodzeniem. Traktuj to jako wskazówkę, a nie gwarancję. Worker nadal może zwrócić błąd przy kolejnym żądaniu POST.

Zobacz także

/integrations/cloudflare/production-usage/ — podłączenie mechanizmu zastępczego, telemetria oraz archiwizacja w R2.
/integrations/cloudflare/troubleshooting/ — mapowanie każdego błędu na właściwy wyjątek i komunikat.
/integrations/cloudflare/configuration/ — pełna dokumentacja pól.