Snelstart — eerste edge-render

In één oogopslag

Op deze pagina zet je één Hypertext Markup Language-string (HTML) om in een Portable Document Format-bestand (PDF). Elke aanroep correspondeert met een methode; het gedrag van elke methode wordt geverifieerd in tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php.

Vereisten

• Een Worker-eindpunt dat het rendercontract via Hypertext Transfer Protocol Secure (HTTPS) aanbiedt.
• Een bearertoken dat de Worker accepteert.
• Een PHP Standards Recommendation 18-client (PSR-18) en PHP Standards Recommendation 17-factory’s (PSR-17) die op het pad beschikbaar zijn (zie /integrations/cloudflare/install/).

Het Worker-contract zoals CloudflareResponseParser het ziet: bij succes retourneert Hypertext Transfer Protocol (HTTP) 200. Het antwoord bevat ofwel Content-Type: application/pdf (ruwe PDF-bytes), of Content-Type: application/json met een base64-pdf-veld. Elke andere status dan 200 en elke body die niet met de markering %PDF begint, wordt als fout behandeld.

Stap 1 — Stel de configuratie samen

<?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'),
);

Het token komt uit de omgeving en wordt nooit hardgecodeerd. workerUrl moet HTTPS gebruiken. Geef je een http://-URL door, dan wijst de bridge die af met Worker URL must use HTTPS voordat er een verzoek wordt verstuurd.

Stap 2 — Bouw de 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
);

De constructor heeft vier verplichte argumenten: de configuratie, de PSR-18-client, de request-factory en de stream-factory. Vier andere argumenten zijn optioneel: de logger, de local-renderer-factory, een expliciet HTML-beveiligingsbeleid en de response-factory. Als je de response-factory meegeeft, schakelt dat het vastgepinde client URL-transport (cURL) in wanneer een opgeloste Internet Protocol-set (IP) of een Subject Public Key Info-pinset (SPKI) aanwezig is (zie /integrations/cloudflare/security-and-operations/).

Stap 3 — Render en schrijf weg

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() gebruikt standaard de A4-breedte (595.28 PDF-punten) en een automatisch gedetecteerde hoogte (heightPt: 0). De twee uitzonderingstypen zijn bewust gescheiden. CloudflareRenderException duidt op een fout aan de Worker-zijde; de aanroep wordt niet opnieuw met een fallback geprobeerd. CloudflareNotAvailableException betekent dat de edge niet bereikbaar was en dat er geen lokale fallback beschikbaar was.

Stap 4 — Inspecteer het resultaat

CloudflareRenderResult is final readonly. De onderstaande velden worden gevuld vanuit response-headers in het binaire pad, of vanuit JavaScript Object Notation-velden (JSON) in het JSON-pad.

Member	Bron
pdfData	Ruwe PDF-bytes
widthPt	De breedte die je hebt opgevraagd
heightPt	X-Pdf-Height-Pt-header / JSON heightPt; standaard 841.89 (A4-hoogte) wanneer deze afwezig of niet-positief is
contentHeightPx	X-Content-Height-Px / JSON contentHeightPx
renderLocation	Afgeleid uit het achtervoegsel van de CF-Ray-header (binair pad) of JSON renderLocation
renderTimeMs	X-Render-Time-Ms / JSON renderTimeMs
size()	strlen($pdfData)
isValid()	true wanneer de bytes beginnen met %PDF

Optioneel — aangepast papierformaat, lettertypen, 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 is alleen zinvol wanneer de configuratie r2FontBucket instelt. De payload bevat dan de bucketnaam en de opgevraagde paden naar lettertypebestanden, zodat de Worker ze kan laden.

Optioneel — bereikbaarheidstest

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

isAvailable() stuurt een geauthenticeerd HTTP-HEAD-verzoek naar de Worker-URL. De methode retourneert true wanneer de status lager is dan 500. De methode retourneert false zonder een uitzondering te werpen wanneer de configuratie ongeldig is of het verzoek mislukt. Beschouw dit als een aanwijzing, niet als een garantie. De Worker kan het daaropvolgende POST-verzoek alsnog laten mislukken.

Zie ook

• /integrations/cloudflare/production-usage/ — fallback-bedrading, telemetrie en R2-archivering.
• /integrations/cloudflare/troubleshooting/ — elke fout met de bijbehorende uitzondering en melding.
• /integrations/cloudflare/configuration/ — volledige veldreferentie.