Configurazione del bridge Cloudflare di NextPDF

In sintesi

Tre oggetti di configurazione immutabili governano il pacchetto. Ogni valore predefinito indicato in questa pagina è ricavato dalla firma del costruttore corrispondente in src/Cloudflare/. Non deriva da una specifica né da una stima. Quando questa pagina indica un valore massimo, si tratta di un limite applicato da questo pacchetto. Non è un’affermazione sulle capacità della piattaforma Cloudflare.

CloudflareRendererConfig

Configurazione del renderer. final readonly. Da costruire direttamente o con CloudflareRendererConfig::fromArray().

Campo	Tipo	Predefinito	Significato
workerUrl	string	— (obbligatorio)	URL dell’endpoint del Worker. Deve essere HTTPS.
apiToken	string	— (obbligatorio)	Token Bearer. Contrassegnato con #[SensitiveParameter].
renderTimeout	int	30	Timeout di trasferimento in secondi, applicato dal trasporto cURL vincolato.
defaultCss	string	''	CSS iniettato nel payload prima dell’HTML fornito.
maxHtmlSize	int	5000000	Dimensione massima dell’input HTML, in byte, applicata prima dell’invio della richiesta.
r2FontBucket	?string	null	Nome del bucket R2 per i pacchetti di font personalizzati.
fallbackToLocal	bool	true	Indica se, quando il Worker non è raggiungibile, viene usato un renderer locale come fallback.
pinnedPublicKeys	list<string>	[]	Impronte SPKI SHA-256, nel formato sha256/<base64>.
backupPublicKeys	list<string>	[]	Pin SPKI di backup, mantenuti separati in modo che la rotazione sia convalidata in modo indipendente.

isValid() restituisce true solo quando workerUrl !== '' e apiToken !== ''. allPublicKeyPins() restituisce l’unione deduplicata di pinnedPublicKeys e backupPublicKeys. Il livello TLS accetta un certificato la cui impronta SPKI compare in uno qualsiasi degli elementi di tale unione. Questo corrisponde a RFC 7469 §2.6, secondo cui una connessione vincolata è valida quando l’insieme delle impronte SPKI presentate interseca l’insieme vincolato. RFC 7469 §2.5 descrive il pin di backup come il principale meccanismo di ripristino contro un errore involontario nella convalida del pin. Mantenere almeno un pin di backup, così che una rotazione del certificato non interrompa l’endpoint — vedi /integrations/cloudflare/security-and-operations/.

Mappa delle chiavi di fromArray()

CloudflareRendererConfig::fromArray() legge chiavi in formato snake_case e applica gli stessi valori predefiniti quando una chiave è assente o di tipo errato:

Chiave dell’array	Mappa a
worker_url	workerUrl
api_token	apiToken
render_timeout	renderTimeout (predefinito 30)
default_css	defaultCss
max_html_size	maxHtmlSize (predefinito 5000000)
r2_font_bucket	r2FontBucket
fallback_to_local	fallbackToLocal (predefinito true)
pinned_public_keys	pinnedPublicKeys (i membri non stringa vengono scartati)
backup_public_keys	backupPublicKeys (i membri non stringa vengono scartati)

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

Limiti di dimensione dell’input applicati dal pacchetto

Questi limiti sono applicati da CloudflareSecurityPolicy::validate() prima che qualunque richiesta lasci il processo. I numeri sono ricavati dal codice sorgente:

Limite	Valore	Dove
Input HTML massimo	maxHtmlSize (predefinito 5000000 byte)	CloudflareSecurityPolicy::validate()
Dimensione massima del data-URI base64 dopo la decodifica	13631488 byte (≈13 MB)	CloudflareSecurityPolicy::MAX_DATA_URI_BYTES

Il superamento di uno dei due limiti solleva una RuntimeException con un messaggio che indica la dimensione che ha causato l’errore e il limite. Il limite sul base64 decodificato protegge dalle bombe di decompressione. La policy stima la dimensione decodificata a partire dalla lunghezza del base64 e rifiuta l’input a partire dal limite massimo. Anche un tag <meta http-equiv="refresh"> viene rifiutato, senza distinzione tra maiuscole e minuscole, perché può innescare un reindirizzamento dall’interno della pagina renderizzata.

Il pacchetto dichiara solo i limiti che applica direttamente. Non fa alcuna affermazione sui limiti di richiesta, CPU o memoria propri del Worker. Per tali aspetti, consultare la documentazione ufficiale di Cloudflare e la propria implementazione del Worker.

ApiProtectionConfig

Configurazione del livello facoltativo di protezione che un Worker — o un gateway PHP davanti a esso — applica alle richieste di rendering in entrata. final readonly.

Campo	Tipo	Predefinito	Significato
maxRequestsPerMinute	int	60	Numero massimo di richieste per client al minuto.
maxRequestsPerHour	int	1000	Numero massimo di richieste per client all’ora.
maxPayloadSizeBytes	int	10485760	Payload massimo in entrata (≈10 MB).
allowedOrigins	list<string>	[]	Allowlist CORS. Se vuota, qui non viene espressa alcuna restrizione sull’origine.
requireApiKey	bool	true	Indica se è richiesta una chiave API.
apiKeyHeader	string	'X-Api-Key'	Intestazione che trasporta la chiave API.
rateLimitWindowSeconds	int	60	Durata della finestra al minuto, in secondi.

fromArray() legge max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header e rate_limit_window_seconds. isValid() richiede che ogni campo numerico sia positivo e che apiKeyHeader non sia vuoto.

R2ArchiveConfig

Configurazione per l’archiviazione dei PDF renderizzati su Cloudflare R2 tramite l’API compatibile con S3. final readonly.

Campo	Tipo	Predefinito	Significato
bucketName	string	— (obbligatorio)	Bucket R2. Validato in base alla regola di denominazione S3.
accountId	string	— (obbligatorio)	ID account Cloudflare, usato per costruire l’endpoint predefinito.
accessKeyId	string	— (obbligatorio)	ID della chiave di accesso R2. #[SensitiveParameter].
secretAccessKey	string	— (obbligatorio)	Chiave di accesso segreta R2. #[SensitiveParameter].
endpoint	string	''	Endpoint S3 personalizzato. Se vuoto, il valore predefinito viene costruito a partire da accountId.
pathPrefix	string	'pdfs/'	Prefisso della chiave per gli oggetti caricati.
maxFileSizeBytes	int	104857600	Dimensione massima del caricamento (≈100 MB), applicata prima del caricamento.

Il costruttore rifiuta un bucketName non vuoto che non rispetta la regola compatibile con S3. La regola richiede da 3 a 63 caratteri, caratteri alfanumerici minuscoli e trattini, con inizio e fine in un carattere alfanumerico. Una violazione solleva InvalidArgumentException. isValid() richiede che bucketName, accountId, accessKeyId e secretAccessKey non siano vuoti. Quando endpoint è vuoto, getEndpoint() restituisce https://<accountId>.r2.cloudflarestorage.com.

Gestione dei segreti

apiToken, accessKeyId e secretAccessKey hanno l’attributo #[SensitiveParameter], così PHP li oscura negli stack trace. Fornirli tramite variabili d’ambiente o un gestore di segreti. Non includere mai tali valori nei commit. Gli oggetti di configurazione sono immutabili, quindi un valore impostato una volta non può essere modificato dopo la costruzione.

Vedi anche

• /integrations/cloudflare/quickstart/ — applica questa configurazione a un primo rendering.
• /integrations/cloudflare/production-usage/ — fallback, archiviazione su R2 e protezione delle API collegati tra loro.
• /integrations/cloudflare/security-and-operations/ — pinning, difesa SSRF e rotazione dei segreti.