Integração do NextPDF com a Cloudflare

Visão geral

Esta página mostra o fluxo completo na Cloudflare: instalar o pacote, configurá-lo, renderizar um arquivo em Portable Document Format (PDF) e, opcionalmente, arquivar o resultado. Cada etapa encaminha a renderização por um Cloudflare Worker e pelo R2. Use este guia prático em conjunto com a página conceitual /integrations/cloudflare/overview/ e a referência /integrations/cloudflare/configuration/.

Instalação

composer require nextpdf/cloudflare:^0.1

Em seguida, adicione um cliente PHP Standards Recommendation (PSR)-18 e fábricas PSR-17, como o Guzzle 7. O pacote declara apenas contratos PSR e não inclui nenhum cliente concreto; portanto, você precisa fornecer um. Para ver todos os detalhes, consulte /integrations/cloudflare/install/.

Boot/descoberta automática

A ponte não inclui service provider nem bundle. Construa-a diretamente a partir de colaboradores PSR e de um CloudflareRendererConfig. O framework hospedeiro deve registrá-la no container reutilizando o binding PSR-18 que a aplicação já possui. Para ver a sequência completa de boot e um exemplo de binding de container, consulte /integrations/cloudflare/boot-and-discovery/.

Bindings de container

Registre o CloudflareHtmlRenderer como singleton. Passe o cliente PSR-18, as fábricas de request e de stream do PSR-17 e, opcionalmente, um logger PSR-3. Quando usar o transporte cURL com pinning, passe também uma fábrica de response do PSR-17. Veja o exemplo de binding em /integrations/cloudflare/boot-and-discovery/.

Publicar a configuração

O pacote lê as configurações de um CloudflareRendererConfig. Carregue os segredos do ambiente, nunca de arquivos 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 deve usar o esquema Hypertext Transfer Protocol Secure (HTTPS). O apiToken é #[SensitiveParameter]. Para ver a referência completa dos campos, consulte /integrations/cloudflare/configuration/, que cobre os campos de pin do Subject Public Key Info (SPKI) e todos os valores padrão. A configuração de arquivamento no R2 e a camada de proteção da application programming interface (API) são tratadas em /integrations/cloudflare/production-usage/.

Smoke test de service provider/bundle

Não há service provider para o smoke test. Use esta verificação de boot no lugar:

$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() é uma verificação pura de completude e não faz nenhuma chamada de rede. isAvailable() executa um HEAD autenticado. Ele retorna false sem lançar exceção quando o Worker está fora do ar.

Pontos de entrada da API pública

O pacote expõe esta superfície pública em NextPDF\Cloudflare\:

Tipo	Função
`CloudflareHtmlRenderer`	Ponto de entrada de renderização: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Configuração do renderizador (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Resultado de renderização tipado (`isValid()`, `size()`).
`CloudflareRenderPayload`	Payload JavaScript Object Notation (JSON) do Worker (`toJson()`).
`CloudflareResponseParser`	Parser de resposta do Worker → resultado.
`CloudflareSecurityPolicy`	Validação de entrada e de URL.
`Transport\PinnedCurlTransport`	Transporte PSR-18 com Domain Name System (DNS) fixado / Transport Layer Security (TLS) com pinning.
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Contratos de fallback local.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Proteção de API de entrada.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	Arquivamento no R2.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Hierarquia de exceções.

Para ver um passo a passo completo de renderização, consulte /integrations/cloudflare/quickstart/. Para a integração em produção, consulte /integrations/cloudflare/production-usage/, que cobre fallback, telemetria, arquivamento e proteção.

Veja também

/integrations/cloudflare/overview/ — o limite de confiança e o modelo de renderização na edge.
/integrations/cloudflare/quickstart/ — uma primeira renderização executável.
/integrations/cloudflare/boot-and-discovery/ — detalhes da integração no container.
/integrations/cloudflare/security-and-operations/ — defesa contra server-side request forgery (SSRF), pinning e o runbook operacional.
/integrations/cloudflare/troubleshooting/ — modos de falha mapeados para exceções.