NextPDF-Cloudflare-Integration

Auf einen Blick

Diese Seite führt Sie durch den gesamten Ablauf von Anfang bis Ende. Installieren Sie das Paket, konfigurieren Sie es, rendern Sie ein PDF und archivieren Sie das Ergebnis, falls gewünscht. Jeder Schritt führt das NextPDF-Rendering über einen Cloudflare Worker und R2 aus. Diese How-to-Seite ergänzt die konzeptionelle Seite /integrations/cloudflare/overview/ und die Referenz /integrations/cloudflare/configuration/.

Installation

composer require nextpdf/cloudflare:^0.1

Fügen Sie anschließend einen PSR-18-Client und PSR-17-Factories hinzu, etwa Guzzle 7. Das Paket deklariert nur PSR-Contracts und bringt keinen konkreten Client mit; stellen Sie diesen daher selbst bereit. Vollständige Details finden Sie unter /integrations/cloudflare/install/.

Boot/Auto-Discovery

Die Bridge enthält keinen Service Provider und kein Bundle. Konstruieren Sie sie stattdessen direkt aus PSR-Kollaborateuren und einer CloudflareRendererConfig. Ein Host-Framework bindet sie in seinem Container, indem es das vorhandene PSR-18-Binding der Anwendung wiederverwendet. Die vollständige Boot-Sequenz und ein Beispiel für ein Container-Binding finden Sie unter /integrations/cloudflare/boot-and-discovery/.

Container-Bindings

Binden Sie CloudflareHtmlRenderer als Singleton. Übergeben Sie den PSR-18-Client, die PSR-17-Request- und -Stream-Factories sowie einen optionalen PSR-3-Logger. Für den gepinnten cURL-Transport übergeben Sie zusätzlich eine PSR-17-Response-Factory. Das Binding-Beispiel finden Sie unter /integrations/cloudflare/boot-and-discovery/.

Konfiguration veröffentlichen

Das Paket liest seine Einstellungen aus einer CloudflareRendererConfig. Beziehen Sie geheime Werte aus der Umgebung, niemals aus eingecheckten Dateien:

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => getenv('CF_WORKER_URL') ?: '',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => getenv('CF_R2_FONT_BUCKET') ?: null,
]);

workerUrl muss HTTPS verwenden. apiToken ist #[SensitiveParameter]. Die vollständige Feldreferenz finden Sie unter /integrations/cloudflare/configuration/; sie behandelt die SPKI-Pin-Felder und alle Standardwerte. Die Konfiguration der R2-Archivierung und die API-Schutzschicht werden unter /integrations/cloudflare/production-usage/ behandelt.

Service-Provider-/Bundle-Smoke-Test

Es gibt keinen Service Provider, den Sie per Smoke-Test prüfen könnten. Die entsprechende Boot-Prüfung sieht so aus:

$config = CloudflareRendererConfig::fromArray($appConfig['cloudflare']);
assert($config->isValid(), 'Cloudflare config incomplete');

// Optional runtime reachability check (authenticated HTTP HEAD):
if (!$renderer->isAvailable()) {
    // Worker not reachable — degrade or alert.
}

isValid() ist eine reine Vollständigkeitsprüfung ohne Netzwerkaufruf. isAvailable() führt einen authentifizierten HEAD durch. Die Methode gibt false zurück, ohne eine Ausnahme zu werfen, wenn der Worker nicht erreichbar ist.

Öffentliche API-Einstiegspunkte

Die öffentliche Oberfläche des Pakets umfasst die folgenden Klassen, alle unter NextPDF\Cloudflare\:

Typ	Rolle
`CloudflareHtmlRenderer`	Render-Einstiegspunkt: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Renderer-Konfiguration (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Typisiertes Render-Ergebnis (`isValid()`, `size()`).
`CloudflareRenderPayload`	Worker-JSON-Payload (`toJson()`).
`CloudflareResponseParser`	Parser für Worker-Antwort → Ergebnis.
`CloudflareSecurityPolicy`	Eingabe- und URL-Validierung.
`Transport\PinnedCurlTransport`	PSR-18-Transport mit DNS-/TLS-Pinning.
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Contracts für den lokalen Fallback.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Schutz eingehender API-Anfragen.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	R2-Archivierung.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Exception-Hierarchie.

Eine vollständige Anleitung zum Rendern finden Sie unter /integrations/cloudflare/quickstart/. Die Produktionsverdrahtung finden Sie unter /integrations/cloudflare/production-usage/; sie behandelt Fallback, Telemetrie, Archivierung und Schutz.

Siehe auch

/integrations/cloudflare/overview/ — Vertrauensgrenze und Edge-Rendering-Modell.
/integrations/cloudflare/quickstart/ — ein erstes lauffähiges Rendering.
/integrations/cloudflare/boot-and-discovery/ — Details zur Container-Verdrahtung.
/integrations/cloudflare/security-and-operations/ — SSRF-Abwehr, Pinning und das Betriebs-Runbook.
/integrations/cloudflare/troubleshooting/ — Fehlermodi, die auf Exceptions abgebildet werden.