De NextPDF-Cloudflare-bridge configureren

In het kort

Drie onveranderlijke configuratieobjecten sturen het pakket aan. Elke standaardwaarde op deze pagina is afkomstig uit de bijbehorende constructorsignatuur in src/Cloudflare/; niet uit een specificatie of een schatting. Waar deze pagina een maximum noemt, is dat een limiet die dit pakket afdwingt. Het zegt niets over de capaciteit van het Cloudflare-platform.

CloudflareRendererConfig

De configuratie van de renderer. final readonly. Maak deze rechtstreeks aan of met CloudflareRendererConfig::fromArray().

Veld	Type	Standaard	Betekenis
workerUrl	string	— (vereist)	URL van het Worker-endpoint. Moet HTTPS zijn.
apiToken	string	— (vereist)	Bearer-token. Gemarkeerd met #[SensitiveParameter].
renderTimeout	int	30	Overdrachtstime-out in seconden, toegepast door het vastgezette cURL-transport.
defaultCss	string	''	CSS die vóór je HTML in de payload wordt geïnjecteerd.
maxHtmlSize	int	5000000	Maximale grootte van de HTML-invoer, in bytes, afgedwongen voordat de aanvraag wordt verzonden.
r2FontBucket	?string	null	Naam van de R2-bucket voor aangepaste lettertypepakketten.
fallbackToLocal	bool	true	Bepaalt of er bij een onbereikbare Worker wordt teruggevallen op een lokale renderer.
pinnedPublicKeys	list<string>	[]	SHA-256-SPKI-vingerafdrukken, formaat sha256/<base64>.
backupPublicKeys	list<string>	[]	Reserve-SPKI-pins, apart gehouden zodat rotatie onafhankelijk wordt gevalideerd.

isValid() geeft alleen true terug als workerUrl !== '' en apiToken !== ''. allPublicKeyPins() geeft de ontdubbelde unie van pinnedPublicKeys en backupPublicKeys terug. De TLS-laag accepteert een certificaat waarvan de SPKI-hash voorkomt in een willekeurig element van die unie. Dit komt overeen met RFC 7469 §2.6: een vastgezette verbinding wordt gevalideerd wanneer de set aangeboden SPKI-vingerafdrukken een doorsnede heeft met de vastgezette set. RFC 7469 §2.5 beschrijft de reserve-pin als het primaire herstelmechanisme bij onbedoelde fouten in de pin-validatie. Houd ten minste één reserve-pin aan zodat certificaatrotatie het endpoint niet onderbreekt — zie /integrations/cloudflare/security-and-operations/.

fromArray()-sleuteltoewijzing

CloudflareRendererConfig::fromArray() leest snake_case-sleutels en past dezelfde standaardwaarden toe als een sleutel ontbreekt of het verkeerde type heeft:

Array-sleutel	Wijst naar
worker_url	workerUrl
api_token	apiToken
render_timeout	renderTimeout (standaard 30)
default_css	defaultCss
max_html_size	maxHtmlSize (standaard 5000000)
r2_font_bucket	r2FontBucket
fallback_to_local	fallbackToLocal (standaard true)
pinned_public_keys	pinnedPublicKeys (niet-string-elementen worden weggelaten)
backup_public_keys	backupPublicKeys (niet-string-elementen worden weggelaten)

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

Door het pakket afgedwongen limieten voor invoergrootte

Deze limieten worden afgedwongen door CloudflareSecurityPolicy::validate() voordat een aanvraag vanuit het proces wordt verstuurd. De getallen zijn afkomstig uit de broncode:

Limiet	Waarde	Waar
Maximale HTML-invoer	maxHtmlSize (standaard 5000000 bytes)	CloudflareSecurityPolicy::validate()
Maximale gedecodeerde grootte van een base64-data-URI	13631488 bytes (≈13 MB)	CloudflareSecurityPolicy::MAX_DATA_URI_BYTES

Als een van beide wordt overschreden, wordt een RuntimeException opgeworpen met een bericht dat de grootte die de limiet overschrijdt en de limiet zelf noemt. Het base64-plafond beschermt tegen decompressiebommen. Het beleid schat de gedecodeerde grootte op basis van de base64-lengte en weigert de aanvraag zodra de schatting op of boven het plafond uitkomt. Een <meta http-equiv="refresh">-tag wordt ook geweigerd, ongeacht hoofdletters of kleine letters, omdat die een redirect vanuit de gerenderde pagina kan starten.

Het pakket vermeldt alleen de limieten die het zelf afdwingt. Het doet geen uitspraak over de aanvraag-, CPU- of geheugenplafonds van de Worker zelf. Raadpleeg de officiële Cloudflare-documentatie en je Worker-implementatie voor die waarden.

ApiProtectionConfig

Configuratie voor de optionele aanvraagbeschermingslaag die een Worker — of een PHP-gateway ervoor — toepast op inkomende render-aanvragen. final readonly.

Veld	Type	Standaard	Betekenis
maxRequestsPerMinute	int	60	Aanvraagplafond per client per minuut.
maxRequestsPerHour	int	1000	Aanvraagplafond per client per uur.
maxPayloadSizeBytes	int	10485760	Maximale inkomende payload (≈10 MB).
allowedOrigins	list<string>	[]	CORS-toelatingslijst. Leeg betekent dat deze configuratie geen oorsprongsbeperking uitdrukt.
requireApiKey	bool	true	Of een API-sleutel vereist is.
apiKeyHeader	string	'X-Api-Key'	Header die de API-sleutel bevat.
rateLimitWindowSeconds	int	60	Lengte van het minuutvenster, in seconden.

fromArray() leest max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header en rate_limit_window_seconds. isValid() vereist dat alle numerieke velden positief zijn en dat apiKeyHeader niet leeg is.

R2ArchiveConfig

Configuratie voor het archiveren van gerenderde PDF’s naar Cloudflare R2 via de S3-compatibele API. final readonly.

Veld	Type	Standaard	Betekenis
bucketName	string	— (vereist)	R2-bucket. Gevalideerd aan de hand van de S3-naamgevingsregel.
accountId	string	— (vereist)	Cloudflare-account-ID, gebruikt om het standaard-endpoint op te bouwen.
accessKeyId	string	— (vereist)	R2-toegangssleutel-ID. #[SensitiveParameter].
secretAccessKey	string	— (vereist)	Geheime R2-toegangssleutel. #[SensitiveParameter].
endpoint	string	''	Aangepast S3-endpoint. Als dit leeg is, wordt het standaard-endpoint opgebouwd uit accountId.
pathPrefix	string	'pdfs/'	Sleutelvoorvoegsel voor geüploade objecten.
maxFileSizeBytes	int	104857600	Maximale uploadgrootte (≈100 MB), afgedwongen vóór de upload.

De constructor weigert een niet-lege bucketName die niet aan de S3-compatibele regel voldoet. Die regel luidt: 3–63 tekens, kleine letters, cijfers en koppeltekens, beginnend en eindigend met een alfanumeriek teken. Bij een overtreding wordt InvalidArgumentException opgeworpen. isValid() vereist dat bucketName, accountId, accessKeyId en secretAccessKey niet leeg zijn. Als endpoint leeg is, geeft getEndpoint() https://<accountId>.r2.cloudflarestorage.com terug.

Omgaan met geheimen

apiToken, accessKeyId en secretAccessKey dragen het #[SensitiveParameter]-attribuut, zodat PHP ze in stacktraces maskeert. Lever ze aan vanuit omgevingsvariabelen of een secrets manager. Leg ze nooit vast in versiebeheer. Configuratieobjecten zijn onveranderlijk, dus een eenmaal ingestelde waarde kan na constructie niet worden gewijzigd.

Zie ook

• /integrations/cloudflare/quickstart/ — pas deze configuratie toe bij een eerste render.
• /integrations/cloudflare/production-usage/ — fallback, R2-archivering en API-bescherming samen inzetten.
• /integrations/cloudflare/security-and-operations/ — pinning, SSRF-verdediging en rotatie van geheimen.