NextPDF-Cloudflare-Brücke konfigurieren

Auf einen Blick

Das Paket wird über drei unveränderliche Konfigurationsobjekte gesteuert. Jeder Standardwert auf dieser Seite stammt aus der entsprechenden Konstruktorsignatur in src/Cloudflare/, nicht aus einer Spezifikation oder Schätzung. Wenn diese Seite ein Maximum angibt, ist dieses Maximum ein Limit, das dieses Paket erzwingt. Es sagt nichts über die Plattformkapazität von Cloudflare aus.

CloudflareRendererConfig

Die Renderer-Konfiguration. final readonly. Konstruieren Sie sie direkt oder mit CloudflareRendererConfig::fromArray().

Feld	Typ	Standard	Bedeutung
workerUrl	string	— (erforderlich)	URL des Worker-Endpunkts. Sie muss HTTPS verwenden.
apiToken	string	— (erforderlich)	Bearer-Token. Mit #[SensitiveParameter] markiert.
renderTimeout	int	30	Übertragungs-Timeout in Sekunden, angewendet vom gepinnten cURL-Transport.
defaultCss	string	''	CSS, das vor Ihrem HTML in die Payload injiziert wird.
maxHtmlSize	int	5000000	Maximale HTML-Eingabegröße in Bytes, die erzwungen wird, bevor die Anfrage gesendet wird.
r2FontBucket	?string	null	R2-Bucket-Name für benutzerdefinierte Schriftpakete.
fallbackToLocal	bool	true	Gibt an, ob bei einem nicht erreichbaren Worker auf einen lokalen Renderer zurückgegriffen wird.
pinnedPublicKeys	list<string>	[]	SHA-256-SPKI-Fingerabdrücke, Format sha256/<base64>.
backupPublicKeys	list<string>	[]	Backup-SPKI-Pins, separat vorgehalten, damit die Rotation unabhängig validiert wird.

isValid() gibt nur dann true zurück, wenn workerUrl !== '' und apiToken !== '' gelten. allPublicKeyPins() gibt die deduplizierte Vereinigung von pinnedPublicKeys und backupPublicKeys zurück. Die TLS-Schicht akzeptiert ein Zertifikat, dessen SPKI-Hash in einem beliebigen Element dieser Vereinigung vorkommt. Dies entspricht RFC 7469 §2.6, wonach eine gepinnte Verbindung validiert wird, wenn sich die Menge der präsentierten SPKI-Fingerabdrücke mit der gepinnten Menge überschneidet. RFC 7469 §2.5 beschreibt den Backup-Pin als primären Wiederherstellungsmechanismus, falls die Pin-Validierung versehentlich fehlschlägt. Halten Sie mindestens einen Backup-Pin vor, damit eine Zertifikatsrotation den Endpunkt nicht unbrauchbar macht — siehe /integrations/cloudflare/security-and-operations/.

fromArray()-Schlüsselzuordnung

CloudflareRendererConfig::fromArray() liest snake_case-Schlüssel und verwendet dieselben Standardwerte, wenn ein Schlüssel fehlt oder den falschen Typ hat:

Array-Schlüssel	Zugeordnet zu
worker_url	workerUrl
api_token	apiToken
render_timeout	renderTimeout (Standard 30)
default_css	defaultCss
max_html_size	maxHtmlSize (Standard 5000000)
r2_font_bucket	r2FontBucket
fallback_to_local	fallbackToLocal (Standard true)
pinned_public_keys	pinnedPublicKeys (Nicht-String-Elemente werden verworfen)
backup_public_keys	backupPublicKeys (Nicht-String-Elemente werden verworfen)

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => 'https://pdf-renderer.example.workers.dev/render',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => 'pdf-fonts',
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Eingabegrößen-Limits, die das Paket erzwingt

Diese Limits werden von CloudflareSecurityPolicy::validate() erzwungen, bevor eine Anfrage den Prozess verlässt. Die Zahlen stammen aus dem Quellcode:

Limit	Wert	Wo
Maximale HTML-Eingabe	maxHtmlSize (Standard 5000000 Bytes)	CloudflareSecurityPolicy::validate()
Maximale dekodierte base64-Data-URI-Größe	13631488 Bytes (≈13 MB)	CloudflareSecurityPolicy::MAX_DATA_URI_BYTES

Wenn eines dieser Limits überschritten wird, löst dies eine RuntimeException mit einer Meldung aus, die die beanstandete Größe und das Limit benennt. Die base64-Obergrenze schützt vor Dekompressionsbomben. Die Policy schätzt die dekodierte Größe aus der base64-Länge und weist die Eingabe ab Erreichen der Obergrenze ab. Ein <meta http-equiv="refresh">-Tag wird ebenfalls abgewiesen, unabhängig von der Groß-/Kleinschreibung, weil es eine Weiterleitung aus der gerenderten Seite heraus auslösen kann.

Das Paket nennt nur die Limits, die es selbst erzwingt. Es trifft keine Aussage über die Anfrage-, CPU- oder Speicher-Obergrenzen des Workers selbst. Konsultieren Sie dafür die offizielle Cloudflare-Dokumentation und Ihre Worker-Implementierung.

ApiProtectionConfig

Konfiguration der optionalen Schutzschicht für Anfragen, die ein Worker — oder ein davor geschaltetes PHP-Gateway — auf eingehende Render-Anfragen anwendet. final readonly.

Feld	Typ	Standard	Bedeutung
maxRequestsPerMinute	int	60	Obergrenze für Anfragen pro Client und Minute.
maxRequestsPerHour	int	1000	Obergrenze für Anfragen pro Client und Stunde.
maxPayloadSizeBytes	int	10485760	Maximale eingehende Payload (≈10 MB).
allowedOrigins	list<string>	[]	CORS-Allowlist. Eine leere Liste bedeutet, dass hier keine Origin-Beschränkung festgelegt wird.
requireApiKey	bool	true	Ob ein API-Schlüssel erforderlich ist.
apiKeyHeader	string	'X-Api-Key'	Header, der den API-Schlüssel enthält.
rateLimitWindowSeconds	int	60	Länge des Minutenfensters in Sekunden.

fromArray() liest max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header und rate_limit_window_seconds. isValid() verlangt, dass alle numerischen Felder positiv sind und apiKeyHeader nicht leer ist.

R2ArchiveConfig

Konfiguration zur Archivierung gerenderter PDFs in Cloudflare R2 über die S3-kompatible API. final readonly.

Feld	Typ	Standard	Bedeutung
bucketName	string	— (erforderlich)	R2-Bucket. Validiert gegen die S3-Namensregel.
accountId	string	— (erforderlich)	Cloudflare-Konto-ID, verwendet zum Erstellen des Standard-Endpunkts.
accessKeyId	string	— (erforderlich)	R2-Access-Key-ID. #[SensitiveParameter].
secretAccessKey	string	— (erforderlich)	Geheimer R2-Access-Key. #[SensitiveParameter].
endpoint	string	''	Benutzerdefinierter S3-Endpunkt. Ist der Wert leer, wird der Standard aus accountId erstellt.
pathPrefix	string	'pdfs/'	Schlüsselpräfix für hochgeladene Objekte.
maxFileSizeBytes	int	104857600	Maximale Upload-Größe (≈100 MB), die vor dem Upload erzwungen wird.

Der Konstruktor lehnt einen nicht leeren bucketName ab, der nicht der S3-kompatiblen Regel entspricht. Diese Regel lautet: 3–63 Zeichen, nur Kleinbuchstaben, Ziffern und Bindestriche, beginnend und endend mit einem alphanumerischen Zeichen. Ein Verstoß löst InvalidArgumentException aus. isValid() verlangt, dass bucketName, accountId, accessKeyId und secretAccessKey nicht leer sind. Wenn endpoint leer ist, gibt getEndpoint() https://<accountId>.r2.cloudflarestorage.com zurück.

Umgang mit Geheimnissen

apiToken, accessKeyId und secretAccessKey sind mit dem Attribut #[SensitiveParameter] versehen, sodass PHP sie in Stack-Traces maskiert. Beziehen Sie sie aus Umgebungsvariablen oder einem Secrets-Manager. Nehmen Sie sie niemals in Commits auf. Konfigurationsobjekte sind unveränderlich, sodass ein einmal gesetzter Wert nach der Konstruktion nicht mehr verändert werden kann.

Siehe auch

• /integrations/cloudflare/quickstart/ — wenden Sie diese Konfiguration in einem ersten Render an.
• /integrations/cloudflare/production-usage/ — Fallback, R2-Archivierung und API-Schutz gemeinsam verdrahten.
• /integrations/cloudflare/security-and-operations/ — Pinning, SSRF-Abwehr und Geheimnisrotation.