Configurar a ponte Cloudflare no NextPDF

Visão geral

O pacote é governado por três objetos de configuração imutáveis. Cada padrão nesta página é lido da assinatura do construtor correspondente em src/Cloudflare/. Ele não vem de uma especificação nem de uma estimativa. Quando esta página informa um máximo, esse máximo é um limite que este pacote impõe. Não é uma afirmação sobre a capacidade da plataforma Cloudflare.

CloudflareRendererConfig

A configuração do renderizador. final readonly. Instancie-a diretamente ou com CloudflareRendererConfig::fromArray().

Campo	Tipo	Padrão	Significado
workerUrl	string	— (obrigatório)	URL do endpoint do Worker. Deve ser HTTPS.
apiToken	string	— (obrigatório)	Token Bearer. Marcado com #[SensitiveParameter].
renderTimeout	int	30	Timeout de transferência em segundos, aplicado pelo transporte cURL fixado.
defaultCss	string	''	CSS injetado no payload antes do HTML.
maxHtmlSize	int	5000000	Tamanho máximo da entrada HTML, em bytes, imposto antes do envio da requisição.
r2FontBucket	?string	null	Nome do bucket R2 para pacotes de fontes personalizadas.
fallbackToLocal	bool	true	Se um Worker inacessível deve recorrer a um renderizador local.
pinnedPublicKeys	list<string>	[]	Fingerprints SPKI SHA-256, formato sha256/<base64>.
backupPublicKeys	list<string>	[]	Pins SPKI de backup, mantidos separados para que a rotação seja validada de forma independente.

isValid() retorna true somente quando workerUrl !== '' e apiToken !== ''. allPublicKeyPins() retorna a união desduplicada de pinnedPublicKeys e backupPublicKeys. A camada TLS aceita um certificado cujo hash SPKI apareça em qualquer membro dessa união. Isso corresponde ao RFC 7469 §2.6, que valida uma conexão fixada quando o conjunto de fingerprints SPKI apresentados faz interseção com o conjunto fixado. O RFC 7469 §2.5 descreve o pin de backup como o principal mecanismo de recuperação contra falhas acidentais na validação de pin. Mantenha pelo menos um pin de backup para que uma rotação de certificado não quebre o endpoint — consulte /integrations/cloudflare/security-and-operations/.

fromArray() — mapa de chaves

CloudflareRendererConfig::fromArray() lê chaves snake_case e aplica os mesmos padrões quando uma chave está ausente ou é do tipo errado:

Chave do array	Mapeia para
worker_url	workerUrl
api_token	apiToken
render_timeout	renderTimeout (padrão 30)
default_css	defaultCss
max_html_size	maxHtmlSize (padrão 5000000)
r2_font_bucket	r2FontBucket
fallback_to_local	fallbackToLocal (padrão true)
pinned_public_keys	pinnedPublicKeys (membros que não são string são descartados)
backup_public_keys	backupPublicKeys (membros que não são string são descartados)

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

Limites de tamanho de entrada que o pacote impõe

Esses limites são impostos por CloudflareSecurityPolicy::validate() antes que qualquer requisição saia do processo. Os números são lidos do código-fonte:

Limite	Valor	Onde
Entrada HTML máxima	maxHtmlSize (padrão 5000000 bytes)	CloudflareSecurityPolicy::validate()
Tamanho máximo do data-URI base64 decodificado	13631488 bytes (≈13 MB)	CloudflareSecurityPolicy::MAX_DATA_URI_BYTES

Exceder qualquer um deles gera uma RuntimeException com uma mensagem que informa o tamanho infrator e o limite. O teto de base64 é uma proteção contra bombas de descompressão. A política estima o tamanho decodificado a partir do comprimento do base64 e rejeita a entrada ao atingir ou ultrapassar o teto. Uma tag <meta http-equiv="refresh"> também é rejeitada, sem diferenciar maiúsculas de minúsculas, porque pode acionar um redirecionamento de dentro da página renderizada.

O pacote informa apenas os limites que ele próprio impõe. Ele não faz nenhuma afirmação sobre os tetos de requisição, CPU ou memória do próprio Worker. Consulte a documentação oficial da Cloudflare e a implementação do seu Worker para esses limites.

ApiProtectionConfig

Configuração da camada opcional de proteção de requisições que um Worker — ou um gateway PHP à frente dele — aplica às requisições de renderização recebidas. final readonly.

Campo	Tipo	Padrão	Significado
maxRequestsPerMinute	int	60	Teto de requisições por cliente por minuto.
maxRequestsPerHour	int	1000	Teto de requisições por cliente por hora.
maxPayloadSizeBytes	int	10485760	Carga útil máxima de entrada (≈10 MB).
allowedOrigins	list<string>	[]	Lista de permissões CORS. Quando vazia, nenhuma restrição de origem é expressa aqui.
requireApiKey	bool	true	Se uma chave de API é obrigatória.
apiKeyHeader	string	'X-Api-Key'	Cabeçalho que transporta a chave de API.
rateLimitWindowSeconds	int	60	Duração da janela por minuto, em segundos.

fromArray() lê 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() exige que todos os campos numéricos sejam positivos e que apiKeyHeader não seja vazio.

R2ArchiveConfig

Configuração para arquivar PDFs renderizados no Cloudflare R2 via API compatível com S3. final readonly.

Campo	Tipo	Padrão	Significado
bucketName	string	— (obrigatório)	Bucket R2. Validado conforme a regra de nomenclatura do S3.
accountId	string	— (obrigatório)	ID da conta Cloudflare, usado para construir o endpoint padrão.
accessKeyId	string	— (obrigatório)	ID da chave de acesso R2. #[SensitiveParameter].
secretAccessKey	string	— (obrigatório)	Chave de acesso secreta R2. #[SensitiveParameter].
endpoint	string	''	Endpoint S3 personalizado. Vazio constrói o padrão a partir de accountId.
pathPrefix	string	'pdfs/'	Prefixo de chave dos objetos enviados.
maxFileSizeBytes	int	104857600	Tamanho máximo de upload (≈100 MB), imposto antes do upload.

O construtor rejeita um bucketName não vazio que não corresponda à regra compatível com S3. A regra exige: 3 a 63 caracteres, alfanuméricos minúsculos e hifens, começando e terminando com um alfanumérico. Uma violação gera InvalidArgumentException. isValid() exige que bucketName, accountId, accessKeyId e secretAccessKey não sejam vazios. Quando endpoint está vazio, getEndpoint() retorna https://<accountId>.r2.cloudflarestorage.com.

Tratamento de segredos

apiToken, accessKeyId e secretAccessKey carregam o atributo #[SensitiveParameter], de modo que o PHP os oculta dos stack traces. Forneça esses valores por variáveis de ambiente ou por um gerenciador de segredos. Nunca faça commit deles. Os objetos de configuração são imutáveis, portanto um valor definido uma vez não pode ser alterado após a construção.

Consulte também

• /integrations/cloudflare/quickstart/ — aplique esta configuração na primeira renderização.
• /integrations/cloudflare/production-usage/ — fallback, arquivamento em R2 e proteção de API integrados.
• /integrations/cloudflare/security-and-operations/ — pinning, defesa contra SSRF e rotação de segredos.