Cloudflare-handleiding voor ontwikkelaars

In het kort

Het Cloudflare-pakket verplaatst het renderen van Portable Document Format (PDF) naar een Worker-grens. Behandel Worker-rendering, lokale fallback, API-bescherming en het R2-archief als afzonderlijke mogelijkheden, elk met eigen foutafhandeling.

Gebruik deze handleiding wanneer je edge-renderingdiensten, beschermde render-endpoints, archiefworkflows of lokale fallbackpaden bouwt met nextpdf/cloudflare.

Architectuurgrens

Laag	Eigenaar	Verantwoordelijkheid	Plaats hier niet
Applicatie-endpoint	Applicatie	Autoriseer de aanroeper, normaliseer het renderverzoek en dwing het bedrijfsbeleid af.	Worker-tokens die in code zijn vastgelegd.
API-bescherming	nextpdf/cloudflare en applicatie	API-sleutelcontroles, controles op payloadgrootte en in-process beslissingen over rate-limiting.	Facturering, tenant-rechten of persistente quotahandhaving.
Cloudflare-renderer	nextpdf/cloudflare	Valideer Hypertext Markup Language (HTML) en de Worker Uniform Resource Locator (URL), verzend de render-payload en parse de respons.	Template-rendering of domeinquery’s.
Worker	Applicatie-deployment	Voer Browser Rendering uit en retourneer PDF-bytes of een gestructureerd resultaat.	Opslagbeleid aan de PHP-zijde.
Lokale fallback	Applicatie-deployment	Renderen wanneer de Worker niet beschikbaar is.	Stille fallback die operationele storingen verbergt.
R2-archief	nextpdf/cloudflare	PDF-bestanden uploaden, objectsleutels opbouwen en ondertekende URL’s aanmaken.	Gevoelige bedrijfsmetadata zonder review.

Runtime-levenscyclus

Fase	Gedrag	Ontwikkelaarsactie
Configuratie aanmaken	Laadt de Worker-URL, het API-token, de time-outs, de groottelimieten, de fallback en de pins.	Bewaar geheimen in de deployment-configuratie.
Verzoekbescherming	Optionele ApiProtection valideert de sleutel, de grootte en de rate limit.	Voer dit uit voordat duur renderwerk start.
Renderer-aanroep	CloudflareHtmlRenderer valideert HTML en de Worker-URL en verzendt daarna JavaScript Object Notation (JSON).	Handel onbeschikbaarheid van de Worker en renderfouten afzonderlijk af.
Parsen van respons	CloudflareResponseParser::parse() accepteert binaire PDF-uitvoer of gestructureerde JSON-uitvoer.	Wijs ongeldige of niet-PDF-uitvoer af.
Lokale fallback	Een optionele lokale renderer vangt het falen van de Worker op.	Injecteer alleen een fabriek voor een lokale renderer wanneer de host dit ondersteunt.
R2-archief	R2ArchiveManager slaat PDF-bytes op en maakt ondertekende URL’s aan.	Houd metadata vrij van gevoelige gegevens, tenzij je deze bewust opslaat.

Aanbevolen applicatiestructuur

Pad	Doel
app/Pdf/Cloudflare/*	Applicatiewrapper voor CloudflareHtmlRenderer.
app/Pdf/Workers/*	Data transfer objects (DTO’s) voor Worker-verzoeken en endpointspecifiek beleid.
app/Pdf/Archive/*	Orkestratie van het R2-archief en bewaarbeslissingen.
app/Pdf/Fallback/*	LocalRendererFactoryInterface-implementatie voor toegestane fallback.
tests/Pdf/Cloudflare/*	Tests voor Worker-down, ongeldig token, payload en archief.

Houd het PHP-API-token gescheiden van het Worker-token. PHP authenticeert zich bij de Worker. De Worker moet inkomende verzoeken authenticeren voordat die browserwerk uitvoert.

<?php

use NextPDF\Cloudflare\ApiProtection;
use NextPDF\Cloudflare\ApiProtectionConfig;
use NextPDF\Cloudflare\ApiKeyValidator;

$protection = new ApiProtection(
    new ApiProtectionConfig(maxRequestsPerMinute: 30),
    new ApiKeyValidator([$expectedApiKey]),
);

$result = $protection->checkRequest(
    clientId: $clientId,
    payloadSize: strlen($html),
    apiKey: $presentedApiKey,
);

if (!$result->allowed) {
    return new JsonResponse(['error' => $result->denialReason], 429, $result->toHeaders());
}

Renderer-patroon

Bouw de renderer met PHP Standards Recommendation (PSR)-afhankelijkheden, waaronder PSR-18 en PSR-17, vanuit je framework. Houd de lokale fallback expliciet, zodat operators kunnen zien wanneer het systeem de Worker niet meer gebruikt.

<?php

use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;

$renderer = new CloudflareHtmlRenderer(
    config: CloudflareRendererConfig::fromArray([
        'worker_url' => getenv('NEXTPDF_CLOUDFLARE_WORKER_URL'),
        'api_token' => getenv('NEXTPDF_CLOUDFLARE_API_TOKEN'),
        'render_timeout' => 30,
        'max_html_size' => 1_000_000,
        'fallback_to_local' => false,
    ]),
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
);

$rendered = $renderer->render($html, widthPt: 595.28);

R2-archiefpatroon

Archiveer pas nadat het renderen is geslaagd en het beleid het resultaat goedkeurt. Behandel publieke URL’s en ondertekende URL’s als afzonderlijke beslissingen.

<?php

use NextPDF\Cloudflare\R2ArchiveManager;

$upload = $archive->upload(
    pdfData: $rendered->pdfData,
    filename: 'invoice-1234.pdf',
    metadata: [
        'document_type' => 'invoice',
    ],
);

if ($upload->isValid()) {
    $temporaryUrl = $archive->generateSignedUrl($upload->key, 600);
}

Plaats geen klantnamen, e-mailadressen, factuurtotalen of gereguleerde identificatiegegevens in objectmetadata, tenzij je bewaar- en toegangsbeleid dit uitdrukkelijk toestaat.

Uitbreidingspunten

Uitbreidingspunt	Gebruik het voor	Beperking
LocalRendererFactoryInterface	Lokale fallback via Artisan of een andere renderer.	Moet een object retourneren dat LocalRendererInterface implementeert.
ApiProtectionConfig	Beleid voor API-sleutel, payloadgrootte en rate limit.	In-memory limieten gelden per proces.
ApiKeyValidator	Timing-safe sleutelvalidatie en hulpmiddelen voor sleutelrotatie.	Bewaar geheimen buiten de broncode.
R2ArchiveConfig	Bucket, inloggegevens, padprefix, endpoint en groottelimieten.	Inloggegevens mogen nooit worden gelogd.
PinnedCurlTransport	Afdwingen van Internet Protocol (IP)- en Subject Public Key Info (SPKI)-pins.	Vereist een runtime met cURL-ondersteuning en een respons-factory.
CloudflareResponseParser	Parsen van de Worker-respons.	Wijst ongeldige PDF-uitvoer of foutresponsen af.

Ontwikkelworkflow

1. Bouw eerst een lokaal renderpad.
2. Voeg Worker-rendering toe met een kleine, representatieve HTML-fixture.
3. Schakel verzoekbescherming in voordat je publieke endpoints blootstelt.
4. Voeg R2-upload pas toe nadat de render- en responsstromen stabiel zijn.
5. Test de paden voor Worker-down, ongeldig token, te grote payload, rate limit en R2-falen.
6. Voeg logs toe die onderscheid maken tussen Worker-render, fallback-render, archief-upload en de aanmaak van ondertekende URL’s.

Foutafhandeling

Fout	Waar het moet worden afgehandeld	Aanbevolen respons
Ontbrekende of ongeldige API-sleutel	API-beschermingslaag.	Wijs het verzoek af voordat het renderwerk begint.
Te grote payload	API-bescherming of renderer-validatie.	Retourneer een validatiefout zonder Worker-aanroep.
Onveilige Worker-URL	Beveiligingsbeleid van de renderer.	Laat de configuratie of het verzoek mislukken voordat netwerk-input/output (I/O) plaatsvindt.
Worker niet beschikbaar	Renderer-grens.	Gebruik alleen expliciete fallback wanneer dit is toegestaan; laat het anders zichtbaar mislukken.
R2-uploadfout	Archiefgrens.	Retourneer de PDF-respons als het archief optioneel is; laat het mislukken als het archief volgens het beleid vereist is.
Fout bij pinrotatie	Deployment en operations.	Roteer met back-uppins en een rollbackplan.

Veilige standaardwaarden

Aandachtspunt	Standaardwaarde	Wanneer overschrijven
Fallback	Ingeschakeld via de standaardconfiguratie.	Uitschakelen wanneer lokaal renderen de deployment-isolatie zou schenden.
Maximale HTML-grootte	5,000,000 bytes.	Verlagen voor publieke endpoints.
Time to live (TTL) van ondertekende URL	3600 seconden.	Verkort de TTL voor gevoelige PDF’s.
Pin-sets	Leeg.	Voeg pins alleen toe met een rotatieplan en back-uppins.
Vereiste van API-sleutel	Ingeschakeld via de standaardconfiguratie voor bescherming.	Alleen uitschakelen voor private, reeds geauthenticeerde interne aanroepen.

Testchecklist

• Renderer-tests dekken geldige HTML, te grote HTML, een ongeldige Worker-URL en een foutrespons van de Worker.
• API-beschermingstests dekken een ontbrekende sleutel, een ongeldige sleutel, een te grote payload en een overschreden rate limit.
• R2-tests dekken een geslaagde upload, een te grote upload, een mislukte Hypertext Transfer Protocol (HTTP)-status, een ongeldige bucket en het genereren van een ondertekende URL.
• Fallback-tests verifiëren dat het pad van de lokale renderer expliciet en waarneembaar is.
• Transport-tests dekken gepinde IP’s, public-key-pins, time-out en redirects die volgens beleid zijn uitgeschakeld.
• Observability-tests bevestigen afzonderlijke loggebeurtenissen voor render, fallback, archief en de aanmaak van ondertekende URL’s.