Configuración del puente de Cloudflare de NextPDF

De un vistazo

Tres objetos de configuración inmutables rigen el paquete. Cada valor predeterminado de esta página se toma de la firma del constructor correspondiente en src/Cloudflare/. No procede de una especificación ni de una estimación. Cuando esta página indica un máximo, ese máximo es un límite que este paquete aplica. No es una afirmación sobre la capacidad de la plataforma Cloudflare.

`CloudflareRendererConfig`

Configuración del renderizador. final readonly. Se puede construir directamente o con CloudflareRendererConfig::fromArray().

Campo	Tipo	Predeterminado	Significado
`workerUrl`	`string`	— (obligatorio)	URL del endpoint del Worker. Debe ser HTTPS.
`apiToken`	`string`	— (obligatorio)	Token Bearer. Marcado con `#[SensitiveParameter]`.
`renderTimeout`	`int`	`30`	Tiempo de espera de transferencia en segundos, aplicado por el transporte cURL con pines fijados.
`defaultCss`	`string`	`''`	CSS inyectado en el payload antes del HTML proporcionado.
`maxHtmlSize`	`int`	`5000000`	Tamaño máximo de entrada HTML, en bytes, aplicado antes de enviar la solicitud.
`r2FontBucket`	`?string`	`null`	Nombre del bucket de R2 para paquetes de fuentes personalizadas.
`fallbackToLocal`	`bool`	`true`	Indica si un Worker inalcanzable recurre a un renderizador local.
`pinnedPublicKeys`	`list<string>`	`[]`	Huellas digitales SPKI SHA-256, con formato `sha256/<base64>`.
`backupPublicKeys`	`list<string>`	`[]`	Pines SPKI de respaldo, mantenidos por separado para que la rotación se valide de forma independiente.

isValid() devuelve true solo cuando workerUrl !== '' y apiToken !== ''. allPublicKeyPins() devuelve la unión sin duplicados de pinnedPublicKeys y backupPublicKeys. La capa TLS acepta un certificado cuyo hash SPKI figure en cualquier miembro de esa unión. Esto coincide con RFC 7469 §2.6, que valida una conexión fijada cuando el conjunto de huellas digitales SPKI presentadas tiene intersección con el conjunto fijado. RFC 7469 §2.5 describe el pin de respaldo como el mecanismo principal de recuperación frente a un fallo inadvertido de validación de pines. Conviene mantener al menos un pin de respaldo para evitar que una rotación de certificado rompa el endpoint; ver /integrations/cloudflare/security-and-operations/.

Mapa de claves de `fromArray()`

CloudflareRendererConfig::fromArray() lee claves en snake_case y aplica los mismos valores predeterminados cuando una clave está ausente o tiene un tipo incorrecto:

Clave del array	Se asigna a
`worker_url`	`workerUrl`
`api_token`	`apiToken`
`render_timeout`	`renderTimeout` (predeterminado `30`)
`default_css`	`defaultCss`
`max_html_size`	`maxHtmlSize` (predeterminado `5000000`)
`r2_font_bucket`	`r2FontBucket`
`fallback_to_local`	`fallbackToLocal` (predeterminado `true`)
`pinned_public_keys`	`pinnedPublicKeys` (los miembros que no son cadenas se descartan)
`backup_public_keys`	`backupPublicKeys` (los miembros que no son cadenas se descartan)

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

Límites de tamaño de entrada aplicados por el paquete

CloudflareSecurityPolicy::validate() aplica estos límites antes de que cualquier solicitud salga del proceso. Los números se toman del código fuente:

Límite	Valor	Dónde
Entrada HTML máxima	`maxHtmlSize` (predeterminado `5000000` bytes)	`CloudflareSecurityPolicy::validate()`
Tamaño máximo de URI de datos base64 decodificado	`13631488` bytes (≈13 MB)	`CloudflareSecurityPolicy::MAX_DATA_URI_BYTES`

Si se supera cualquiera de los dos, se genera una RuntimeException con un mensaje que indica el tamaño infractor y el límite. El tope de base64 protege contra bombas de descompresión. La política estima el tamaño decodificado a partir de la longitud de base64 y rechaza la solicitud si se alcanza o supera el tope. Una etiqueta <meta http-equiv="refresh"> también se rechaza, sin distinguir mayúsculas y minúsculas, porque puede provocar una redirección desde dentro de la página renderizada.

El paquete declara únicamente los límites que él mismo aplica. No hace ninguna afirmación sobre los topes de solicitud, CPU o memoria del propio Worker. Consultar la documentación oficial de Cloudflare y la implementación del Worker para conocerlos.

`ApiProtectionConfig`

Configuración de la capa opcional de protección de solicitudes que un Worker — o una pasarela PHP situada delante de él — aplica a las solicitudes de renderizado entrantes. final readonly.

Campo	Tipo	Predeterminado	Significado
`maxRequestsPerMinute`	`int`	`60`	Tope de solicitudes por minuto por cliente.
`maxRequestsPerHour`	`int`	`1000`	Tope de solicitudes por hora por cliente.
`maxPayloadSizeBytes`	`int`	`10485760`	Payload entrante máximo (≈10 MB).
`allowedOrigins`	`list<string>`	`[]`	Lista CORS de orígenes permitidos. Vacía significa que aquí no se expresa ninguna restricción de origen.
`requireApiKey`	`bool`	`true`	Indica si se requiere una clave de API.
`apiKeyHeader`	`string`	`'X-Api-Key'`	Cabecera que transporta la clave de API.
`rateLimitWindowSeconds`	`int`	`60`	Duración de la ventana por minuto, en segundos.

fromArray() lee max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header y rate_limit_window_seconds. isValid() exige que todos los campos numéricos sean positivos y que apiKeyHeader no esté vacío.

`R2ArchiveConfig`

Configuración para archivar los PDF renderizados en Cloudflare R2 a través de la API compatible con S3. final readonly.

Campo	Tipo	Predeterminado	Significado
`bucketName`	`string`	— (obligatorio)	Bucket de R2. Validado contra la regla de nomenclatura de S3.
`accountId`	`string`	— (obligatorio)	ID de cuenta de Cloudflare, utilizado para construir el endpoint predeterminado.
`accessKeyId`	`string`	— (obligatorio)	ID de clave de acceso de R2. `#[SensitiveParameter]`.
`secretAccessKey`	`string`	— (obligatorio)	Clave de acceso secreta de R2. `#[SensitiveParameter]`.
`endpoint`	`string`	`''`	Endpoint S3 personalizado. Si está vacío, se construye el predeterminado a partir de `accountId`.
`pathPrefix`	`string`	`'pdfs/'`	Prefijo de clave para los objetos cargados.
`maxFileSizeBytes`	`int`	`104857600`	Tamaño máximo de subida (≈100 MB), aplicado antes de subir.

El constructor rechaza un bucketName no vacío que no cumpla la regla compatible con S3. Según esa regla, debe tener de 3 a 63 caracteres, usar solo caracteres alfanuméricos en minúscula y guiones, y empezar y terminar con un carácter alfanumérico. Una infracción genera InvalidArgumentException. isValid() exige que bucketName, accountId, accessKeyId y secretAccessKey no estén vacíos. Cuando endpoint está vacío, getEndpoint() devuelve https://<accountId>.r2.cloudflarestorage.com.

Manejo de secretos

apiToken, accessKeyId y secretAccessKey llevan el atributo #[SensitiveParameter], por lo que PHP los oculta en las trazas de pila. Deben proporcionarse desde variables de entorno o desde un gestor de secretos. No deben confirmarse nunca en el repositorio. Los objetos de configuración son inmutables, por lo que un valor establecido una vez no puede modificarse después de la construcción.

Véase también

/integrations/cloudflare/quickstart/ — aplicar esta configuración en un primer renderizado.
/integrations/cloudflare/production-usage/ — el fallback, el archivado en R2 y la protección de la API integrados entre sí.
/integrations/cloudflare/security-and-operations/ — fijado de pines, defensa contra SSRF y rotación de secretos.

Configuración del puente de Cloudflare de NextPDF

De un vistazo

CloudflareRendererConfig

Mapa de claves de fromArray()