Integración de NextPDF con Cloudflare

De un vistazo

Esta página cubre el recorrido completo, de principio a fin: instalar el paquete, configurarlo, renderizar un PDF y, si procede, archivar el resultado. En cada paso, el renderizado de NextPDF se ejecuta mediante un Cloudflare Worker y R2. Es la guía práctica que complementa la página conceptual /integrations/cloudflare/overview/ y la referencia /integrations/cloudflare/configuration/.

Instalación

composer require nextpdf/cloudflare:^0.1

A continuación, añadir un cliente PSR-18 y fábricas PSR-17, como Guzzle 7. El paquete declara únicamente contratos PSR y no incluye ningún cliente concreto propio, por lo que es necesario proporcionar uno. Para más detalles, véase /integrations/cloudflare/install/.

Arranque/descubrimiento automático

El puente no incluye proveedor de servicios ni bundle. En su lugar, construirlo directamente a partir de colaboradores PSR y una CloudflareRendererConfig. El framework anfitrión lo vincula en su contenedor reutilizando el binding PSR-18 existente de la aplicación. Para la secuencia de arranque completa y un ejemplo de binding de contenedor, véase /integrations/cloudflare/boot-and-discovery/.

Bindings del contenedor

Vincular CloudflareHtmlRenderer como singleton. Proporcionarle el cliente PSR-18, las fábricas de petición y de flujo PSR-17 y, opcionalmente, un logger PSR-3. Para el transporte cURL fijado, proporcionar también una fábrica de respuestas PSR-17. Véase el ejemplo de binding en /integrations/cloudflare/boot-and-discovery/.

Publicar la configuración

El paquete lee sus ajustes desde una CloudflareRendererConfig. Los secretos deben obtenerse del entorno, nunca de archivos versionados:

<?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 debe usar HTTPS. apiToken es #[SensitiveParameter]. Para la referencia completa de campos, véase /integrations/cloudflare/configuration/, que cubre los campos de fijación SPKI y todos los valores predeterminados. La configuración de archivado en R2 y la capa de protección de la API se tratan en /integrations/cloudflare/production-usage/.

Prueba de humo del proveedor de servicios/bundle

No existe ningún proveedor de servicios sobre el que ejecutar una prueba de humo. La comprobación de arranque equivalente es la siguiente:

$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() es una comprobación de integridad pura, sin llamada de red. isAvailable() realiza un HEAD autenticado. Devuelve false sin lanzar excepción cuando el Worker no está disponible.

Puntos de entrada de la API pública

La superficie pública del paquete se encuentra íntegramente bajo NextPDF\Cloudflare\:

Tipo	Rol
`CloudflareHtmlRenderer`	Punto de entrada de renderizado: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Configuración del renderizador (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Resultado de renderizado con tipo (`isValid()`, `size()`).
`CloudflareRenderPayload`	Carga JSON del Worker (`toJson()`).
`CloudflareResponseParser`	Analizador de respuesta del Worker → resultado.
`CloudflareSecurityPolicy`	Validación de entradas y URL.
`Transport\PinnedCurlTransport`	Transporte PSR-18 con DNS fijado / TLS fijado.
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Contratos de respaldo local.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Protección de la API entrante.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	Archivado en R2.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Jerarquía de excepciones.

Para un recorrido de renderizado completo, véase /integrations/cloudflare/quickstart/. El cableado de producción se describe en /integrations/cloudflare/production-usage/, que cubre el respaldo, la telemetría, el archivado y la protección.

Véase también

/integrations/cloudflare/overview/ — el límite de confianza y el modelo de renderizado en el borde.
/integrations/cloudflare/quickstart/ — un primer renderizado ejecutable.
/integrations/cloudflare/boot-and-discovery/ — detalles del cableado del contenedor.
/integrations/cloudflare/security-and-operations/ — defensa frente a SSRF, fijación y el runbook operativo.
/integrations/cloudflare/troubleshooting/ — modos de fallo asociados a excepciones.