Guida Cloudflare per sviluppatori

In breve

Il pacchetto Cloudflare sposta il rendering entro un confine Worker. Trattare rendering Worker, fallback locale, protezione API e archivio R2 come funzionalità distinte, ciascuna con una gestione degli errori separata.

Usare questa guida per creare servizi di rendering edge, endpoint di rendering protetti, flussi di lavoro di archiviazione o percorsi di fallback locale basati su nextpdf/cloudflare.

Confine dell’architettura

Livello	Di proprietà di	Responsabilità	Da non inserire qui
Endpoint dell’applicazione	Applicazione	Autorizzare il chiamante, normalizzare la richiesta di rendering, applicare i criteri aziendali.	Token Worker hardcoded nel codice.
Protezione API	nextpdf/cloudflare e applicazione	Decisioni relative a chiave API, dimensione del payload e limitazione della frequenza in-process.	Fatturazione, diritti del tenant o applicazione di quote persistenti.
Renderer Cloudflare	nextpdf/cloudflare	Convalidare HTML e URL del Worker, inviare il payload di rendering, analizzare la risposta.	Rendering dei template o query di dominio.
Worker	Distribuzione dell’applicazione	Eseguire il Browser Rendering e restituire i byte del PDF o un risultato strutturato.	Criteri di archiviazione lato PHP.
Fallback locale	Distribuzione dell’applicazione	Eseguire il rendering quando il Worker non è disponibile.	Fallback silenzioso che nasconde le interruzioni operative.
Archivio R2	nextpdf/cloudflare	Caricare i PDF, costruire le chiavi degli oggetti, creare URL firmati.	Metadati aziendali sensibili senza revisione.

Ciclo di vita di runtime

Fase	Comportamento	Azione dello sviluppatore
Creazione della configurazione	Vengono caricati URL del Worker, token API, timeout, limiti di dimensione, fallback e pin.	Conservare i segreti nella configurazione di distribuzione.
Protezione delle richieste	ApiProtection facoltativo convalida chiave, dimensione e limite di frequenza.	Eseguire prima del costoso lavoro di rendering.
Chiamata al renderer	CloudflareHtmlRenderer convalida HTML e URL del Worker, quindi invia il JSON.	Gestire separatamente Worker non disponibile ed errori di rendering.
Analisi della risposta	CloudflareResponseParser::parse() accetta output PDF binario o JSON strutturato.	Rifiutare output non valido o che non sia un PDF.
Fallback locale	Un renderer locale facoltativo gestisce l’errore del Worker.	Iniettare una factory di renderer locale solo quando l’host la supporta.
Archivio R2	R2ArchiveManager memorizza i byte del PDF e crea URL firmati.	Conservare solo metadati non sensibili, a meno che non vengano memorizzati intenzionalmente.

Struttura dell’applicazione consigliata

Percorso	Scopo
app/Pdf/Cloudflare/*	Wrapper dell’applicazione attorno a CloudflareHtmlRenderer.
app/Pdf/Workers/*	DTO per le richieste Worker e criteri specifici dell’endpoint.
app/Pdf/Archive/*	Orchestrazione dell’archivio R2 e decisioni di conservazione.
app/Pdf/Fallback/*	LocalRendererFactoryInterface da implementare quando il fallback è consentito.
tests/Pdf/Cloudflare/*	Test per Worker non attivo, token non valido, payload e archivio.

Mantenere separati il token API PHP e il token Worker. Il lato PHP si autentica presso il Worker. Il Worker deve autenticare le richieste in ingresso prima di eseguire il lavoro del browser.

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

Pattern del renderer

Costruire il renderer con le dipendenze PSR-18 e PSR-17 del framework. Mantenere esplicito il fallback locale, così gli operatori possono vedere quando il sistema ha smesso di usare il Worker.

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

Pattern dell’archivio R2

Archiviare solo dopo il successo del rendering e l’approvazione dei criteri. Trattare URL pubblici e URL firmati come decisioni distinte.

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

Non inserire nomi di clienti, indirizzi e-mail, importi totali delle fatture o identificatori regolamentati nei metadati degli oggetti, a meno che i criteri di conservazione e accesso non lo consentano esplicitamente.

Punti di estensione

Punto di estensione	Da usare per	Vincolo
LocalRendererFactoryInterface	Fallback locale verso Artisan o un altro renderer.	Deve restituire un oggetto che implementa LocalRendererInterface.
ApiProtectionConfig	Criteri relativi a chiave API, dimensione del payload e limite di frequenza.	I limiti in memoria sono per processo.
ApiKeyValidator	Convalida della chiave a tempo costante e helper per la rotazione delle chiavi.	Conservare i segreti al di fuori del codice sorgente.
R2ArchiveConfig	Bucket, credenziali, prefisso del percorso, endpoint e limiti di dimensione.	Le credenziali non devono mai essere registrate nei log.
PinnedCurlTransport	Applicazione dei pin IP e SPKI.	Richiede un runtime con supporto cURL e una factory di risposte.
CloudflareResponseParser	Analisi della risposta del Worker.	Rifiuta i PDF non validi o le risposte di errore.

Flusso di lavoro di sviluppo

1. Creare prima un percorso di rendering locale.
2. Aggiungere il rendering Worker con un piccolo fixture HTML rappresentativo.
3. Abilitare la protezione delle richieste prima di esporre gli endpoint pubblici.
4. Aggiungere il caricamento R2 solo dopo che i flussi di rendering e risposta sono stabili.
5. Testare i percorsi Worker non attivo, token non valido, payload sovradimensionato, limite di frequenza ed errore R2.
6. Aggiungere log che distinguano rendering Worker, rendering di fallback, caricamento in archivio e creazione di URL firmati.

Gestione degli errori

Errore	Dove gestirlo	Risposta consigliata
Chiave API mancante o non valida	Livello di protezione delle API.	Rifiutare prima che inizi il lavoro di rendering.
Payload sovradimensionato	Protezione delle API o convalida del renderer.	Restituire un errore di convalida senza chiamata al Worker.
URL del Worker non sicuro	Criteri di sicurezza del renderer.	Far fallire la configurazione o la richiesta prima dell’I/O di rete.
Worker non disponibile	Confine del renderer.	Usare il fallback esplicito solo quando è consentito; in caso contrario, far fallire in modo visibile.
Errore di caricamento R2	Confine dell’archivio.	Restituire la risposta PDF se l’archivio è facoltativo; far fallire se l’archivio è richiesto dai criteri.
Errore di rotazione dei pin	Distribuzione e operazioni.	Effettuare la rotazione con pin di backup e un piano di rollback.

Impostazioni predefinite sicure

Aspetto	Predefinito	Quando eseguire l’override
Fallback	Abilitato per impostazione predefinita nella configurazione.	Disabilitare quando il rendering locale violerebbe l’isolamento della distribuzione.
Dimensione massima dell’HTML	5,000,000 byte.	Ridurre per gli endpoint pubblici.
TTL degli URL firmati	3600 secondi.	Ridurre per i PDF sensibili.
Set di pin	Vuoto.	Aggiungere i pin solo con un piano di rotazione e pin di backup.
Requisito della chiave API	Abilitato per impostazione predefinita nella configurazione di protezione.	Disabilitare solo per chiamate interne private e già autenticate.

Elenco di controllo per i test

• I test del renderer coprono HTML valido, HTML sovradimensionato, URL del Worker non valido e risposta di errore del Worker.
• I test di protezione API coprono chiave mancante, chiave non valida, payload troppo grande e limite di frequenza superato.
• I test R2 coprono caricamento riuscito, caricamento troppo grande, stato HTTP di errore, bucket non valido e generazione di URL firmati.
• I test di fallback verificano che il percorso del renderer locale sia esplicito e osservabile.
• I test di trasporto coprono IP con pin, pin di chiave pubblica, timeout e reindirizzamenti disabilitati dai criteri.
• I test di osservabilità verificano la presenza di eventi di log distinti per rendering, fallback, archivio e creazione di URL firmati.