Integrazione Cloudflare per NextPDF

In sintesi

Questa pagina copre l’intero flusso, dall’inizio alla fine. Installare il pacchetto, configurarlo, generare un PDF e — se si desidera — archiviare il risultato. Ogni passaggio instrada il rendering di NextPDF tramite un Cloudflare Worker e R2. È la guida pratica che accompagna la pagina concettuale /integrations/cloudflare/overview/ e il riferimento /integrations/cloudflare/configuration/.

Installazione

composer require nextpdf/cloudflare:^0.1

Aggiungere quindi un client PSR-18 e le factory PSR-17, per esempio Guzzle 7. Il pacchetto dichiara solo i contratti PSR e non include un proprio client concreto; occorre quindi fornirne uno. Per tutti i dettagli, vedere /integrations/cloudflare/install/.

Avvio/rilevamento automatico

Il bridge non include service provider né bundle. Costruirlo direttamente a partire dai collaboratori PSR e da una CloudflareRendererConfig. Un framework ospitante lo registra nel proprio container riutilizzando il binding PSR-18 già presente nell’applicazione. Per la sequenza completa di avvio e un esempio di binding nel container, vedere /integrations/cloudflare/boot-and-discovery/.

Binding del container

Registrare CloudflareHtmlRenderer come singleton. Fornire il client PSR-18, le factory PSR-17 di richiesta e di flusso e un logger PSR-3 facoltativo. Per il transport cURL con pinning, fornire anche una factory di risposta PSR-17. Vedere l’esempio di binding in /integrations/cloudflare/boot-and-discovery/.

Pubblicazione della configurazione

Il pacchetto legge le impostazioni da una CloudflareRendererConfig. Ricavare i segreti dall’ambiente, mai da file inclusi nei commit:

<?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 deve usare HTTPS. apiToken è #[SensitiveParameter]. Per il riferimento completo dei campi, vedere /integrations/cloudflare/configuration/, che descrive i campi del pin SPKI e tutti i valori predefiniti. La configurazione dell’archiviazione R2 e il livello di protezione dell’API sono trattati in /integrations/cloudflare/production-usage/.

Smoke test del service provider/bundle

Non esiste alcun service provider da sottoporre a smoke test. Il controllo di avvio equivalente è il seguente:

$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() esegue solo una verifica di completezza, senza chiamate di rete. isAvailable() esegue un HEAD autenticato. Restituisce false senza sollevare eccezioni quando il Worker non è raggiungibile.

Punti di accesso dell’API pubblica

La superficie pubblica del pacchetto si trova interamente sotto NextPDF\Cloudflare\:

Tipo	Ruolo
`CloudflareHtmlRenderer`	Punto di accesso al rendering: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Configurazione del renderer (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Risultato di rendering tipizzato (`isValid()`, `size()`).
`CloudflareRenderPayload`	Payload JSON del Worker (`toJson()`).
`CloudflareResponseParser`	Parser che converte la risposta del Worker nel risultato.
`CloudflareSecurityPolicy`	Validazione dell’input e dell’URL.
`Transport\PinnedCurlTransport`	Transport PSR-18 con pinning del DNS / pinning TLS.
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Contratti di fallback locale.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Protezione dell’API in ingresso.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	Archiviazione R2.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Gerarchia delle eccezioni.

Per una guida completa al rendering, vedere /integrations/cloudflare/quickstart/. Il cablaggio per la produzione è descritto in /integrations/cloudflare/production-usage/, che illustra fallback, telemetria, archiviazione e protezione.

Vedere anche

/integrations/cloudflare/overview/ — il confine di fiducia e il modello di rendering all’edge.
/integrations/cloudflare/quickstart/ — un primo rendering eseguibile.
/integrations/cloudflare/boot-and-discovery/ — dettagli sul cablaggio del container.
/integrations/cloudflare/security-and-operations/ — difesa contro SSRF, pinning e il runbook operativo.
/integrations/cloudflare/troubleshooting/ — modalità di errore associate alle eccezioni.