Cloudflare-Entwicklerhandbuch

Auf einen Blick

Das Cloudflare-Paket verlagert das Rendering an die Worker-Grenze. Behandeln Sie Worker-Rendering, lokalen Fallback, API-Schutz und R2-Archiv als getrennte Fähigkeiten mit jeweils eigener Fehlerbehandlung.

Nutzen Sie dieses Handbuch, wenn Sie Edge-Rendering-Dienste, geschützte Render-Endpunkte, Archiv-Workflows oder lokale Fallback-Pfade rund um nextpdf/cloudflare aufbauen.

Architekturgrenze

Schicht	Verantwortlich	Verantwortung	Hier nicht ablegen
Anwendungsendpunkt	Anwendung	Aufrufer autorisieren, Render-Anfrage normalisieren und Geschäftsrichtlinien durchsetzen.	Worker-Token im Code speichern.
API-Schutz	nextpdf/cloudflare und Anwendung	Entscheidungen über API-Schlüssel, Payload-Größe und prozessinternes Rate-Limit.	Abrechnung, Mandantenberechtigung oder dauerhafte Quota-Durchsetzung.
Cloudflare-Renderer	nextpdf/cloudflare	HTML und Worker-URL validieren, Render-Payload senden und Antwort parsen.	Template-Rendering oder Domänenabfragen.
Worker	Anwendungs-Deployment	Browser-Rendering ausführen und PDF-Bytes oder ein strukturiertes Ergebnis zurückgeben.	PHP-seitige Speicherrichtlinie.
Lokaler Fallback	Anwendungs-Deployment	Rendern, wenn der Worker nicht verfügbar ist.	Stiller Fallback, der betriebliche Ausfälle verbirgt.
R2-Archiv	nextpdf/cloudflare	PDFs hochladen, Objekt-Keys bilden und signierte URLs erzeugen.	Sensible Geschäftsmetadaten ohne Prüfung.

Laufzeit-Lebenszyklus

Phase	Verhalten	Entwickleraktion
Konfigurationserstellung	Worker-URL, API-Token, Timeouts, Größenlimits, Fallback und Pins werden geladen.	Halten Sie Secrets in der Deployment-Konfiguration.
Anfrageschutz	Die optionale ApiProtection validiert Schlüssel, Größe und Rate-Limit.	Vor aufwendiger Render-Arbeit ausführen.
Renderer-Aufruf	CloudflareHtmlRenderer validiert HTML und Worker-URL und sendet dann JSON.	Nichtverfügbarkeit des Workers und Render-Fehler getrennt behandeln.
Antwort-Parsing	CloudflareResponseParser::parse() akzeptiert binäres PDF oder strukturierte JSON-Ausgabe.	Ablehnen, wenn die Ausgabe ungültig oder kein PDF ist.
Lokaler Fallback	Optionaler lokaler Renderer behandelt Worker-Ausfall.	Eine lokale Renderer-Factory nur bereitstellen, wenn der Host sie unterstützt.
R2-Archiv	R2ArchiveManager speichert PDF-Bytes und erzeugt signierte URLs.	Metadaten unsensibel halten, sofern sensible Daten nicht bewusst gespeichert werden.

Empfohlene Anwendungsstruktur

Pfad	Zweck
app/Pdf/Cloudflare/*	Anwendungs-Wrapper um CloudflareHtmlRenderer.
app/Pdf/Workers/*	Worker-Request-DTOs und endpunktspezifische Richtlinie.
app/Pdf/Archive/*	R2-Archiv-Orchestrierung und Aufbewahrungsentscheidungen.
app/Pdf/Fallback/*	LocalRendererFactoryInterface-Implementierung, wenn Fallback erlaubt ist.
tests/Pdf/Cloudflare/*	Tests für Worker-Ausfall, ungültiges Token, Payload und Archivierung.

Halten Sie das PHP-API-Token und das Worker-Token getrennt. Die PHP-Seite authentifiziert sich gegenüber dem Worker. Der Worker sollte eingehende Anfragen authentifizieren, bevor er Browserarbeit ausführt.

<?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-Muster

Bauen Sie den Renderer mit PSR-18- und PSR-17-Abhängigkeiten aus Ihrem Framework. Halten Sie den lokalen Fallback explizit, damit Betreiber erkennen, wann das System den Worker nicht mehr nutzt.

<?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-Archiv-Muster

Archivieren Sie erst nach erfolgreichem Rendern und Richtlinienfreigabe. Behandeln Sie öffentliche URLs und signierte URLs als getrennte Entscheidungen.

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

Legen Sie keine Kundennamen, E-Mail-Adressen, Rechnungssummen oder regulierten Kennungen in Objektmetadaten ab, sofern Ihre Aufbewahrungs- und Zugriffsrichtlinie es nicht ausdrücklich erlaubt.

Erweiterungspunkte

Erweiterungspunkt	Verwenden für	Einschränkung
LocalRendererFactoryInterface	Lokaler Fallback auf Artisan oder einen anderen Renderer.	Muss ein Objekt zurückgeben, das LocalRendererInterface implementiert.
ApiProtectionConfig	Richtlinie für API-Schlüssel, Payload-Größe und Rate-Limit.	In-Memory-Limits gelten pro Prozess.
ApiKeyValidator	Timing-sichere Schlüsselvalidierung und Hilfsfunktionen für Schlüsselrotation.	Secrets außerhalb des Quellcodes speichern.
R2ArchiveConfig	Bucket, Anmeldedaten, Pfadpräfix, Endpunkt und Größenlimits.	Anmeldedaten dürfen niemals geloggt werden.
PinnedCurlTransport	Durchsetzung von IP- und SPKI-Pins.	Erfordert eine cURL-fähige Laufzeit und eine Response-Factory.
CloudflareResponseParser	Parsen der Worker-Antwort.	Lehnt ungültige PDFs oder Fehlerantworten ab.

Entwicklungs-Workflow

1. Bauen Sie zuerst einen lokalen Render-Pfad.
2. Fügen Sie Worker-Rendering mit einem kleinen, repräsentativen HTML-Fixture hinzu.
3. Aktivieren Sie den Anfrageschutz, bevor Sie öffentliche Endpunkte freigeben.
4. Fügen Sie den R2-Upload erst hinzu, wenn die Render- und Antwortabläufe stabil sind.
5. Testen Sie die Pfade für Worker-Ausfall, ungültiges Token, übergroße Payload, Rate-Limit und R2-Fehler.
6. Fügen Sie Logs hinzu, die Worker-Rendering, Fallback-Rendering, Archiv-Upload und das Erzeugen signierter URLs unterscheiden.

Fehlerbehandlung

Fehler	Wo er behandelt werden sollte	Empfohlene Reaktion
Fehlender oder ungültiger API-Schlüssel	API-Schutzschicht.	Ablehnen, bevor die Render-Arbeit beginnt.
Übergroße Payload	API-Schutz oder Renderer-Validierung.	Einen Validierungsfehler ohne Worker-Aufruf zurückgeben.
Unsichere Worker-URL	Renderer-Sicherheitsrichtlinie.	Konfiguration oder Anfrage vor Netzwerk-I/O fehlschlagen lassen.
Worker nicht verfügbar	Renderer-Grenze.	Expliziten Fallback nur nutzen, wenn erlaubt; andernfalls sichtbar fehlschlagen.
R2-Upload-Fehler	Archivgrenze.	Die PDF-Antwort zurückgeben, wenn das Archiv optional ist; fehlschlagen, wenn das Archiv per Richtlinie erforderlich ist.
Pin-Rotationsfehler	Deployment und Betrieb.	Mit Backup-Pins und einem Rollback-Plan rotieren.

Sichere Standardwerte

Aspekt	Standard	Wann überschreiben
Fallback	Per Konfigurationsstandard aktiviert.	Deaktivieren, wenn lokales Rendering die Deployment-Isolation verletzen würde.
Maximale HTML-Größe	5,000,000 Bytes.	Für öffentliche Endpunkte niedriger ansetzen.
TTL der signierten URL	3600 Sekunden.	Für sensible PDFs verkürzen.
Pin-Sätze	Leer.	Pins nur mit einem Rotationsplan und Backup-Pins hinzufügen.
Anforderung an den API-Schlüssel	Per Schutz-Config-Standard aktiviert.	Nur für private, bereits authentifizierte interne Aufrufe deaktivieren.

Test-Checkliste

• Renderer-Tests decken gültiges HTML, übergroßes HTML, ungültige Worker-URL und Worker-Fehlerantwort ab.
• API-Schutz-Tests decken fehlenden Schlüssel, ungültigen Schlüssel, zu große Payload und überschrittenes Rate-Limit ab.
• R2-Tests decken erfolgreichen Upload, zu großen Upload, HTTP-Fehlerstatus, ungültigen Bucket und das Erzeugen signierter URLs ab.
• Fallback-Tests prüfen, dass der Pfad des lokalen Renderers explizit und beobachtbar ist.
• Transport-Tests decken gepinnte IPs, Public-Key-Pins, Timeout und per Richtlinie deaktivierte Redirects ab.
• Observability-Tests prüfen, dass es eigene Log-Events für Rendering, Fallback, Archiv und das Erzeugen signierter URLs gibt.