Início rápido — primeira renderização na edge

Visão geral

Nesta página, você transforma uma string Hypertext Markup Language (HTML) em um arquivo Portable Document Format (PDF). Cada chamada corresponde a um método, e o comportamento de cada um deles é verificado em tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php.

Pré-requisitos

• Um endpoint de Worker que disponibilize o contrato de renderização sobre Hypertext Transfer Protocol Secure (HTTPS).
• Um bearer token que o Worker aceite.
• Um cliente PHP Standards Recommendation 18 (PSR-18) e fábricas PHP Standards Recommendation 17 (PSR-17) disponíveis no path (veja /integrations/cloudflare/install/).

O contrato do Worker, conforme observado em CloudflareResponseParser, é este: em caso de sucesso, ele retorna Hypertext Transfer Protocol (HTTP) 200. A resposta traz Content-Type: application/pdf (bytes brutos do PDF) ou Content-Type: application/json com um campo pdf em base64. Qualquer status diferente de 200, ou qualquer corpo que não comece com o marcador %PDF, é tratado como falha.

Passo 1 — Construa a configuração

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = new CloudflareRendererConfig(
    workerUrl: 'https://pdf-renderer.example.workers.dev/render',
    apiToken: getenv('CF_PDF_TOKEN') ?: throw new RuntimeException('CF_PDF_TOKEN not set'),
);

O token vem do ambiente e nunca é escrito diretamente no código. workerUrl deve usar HTTPS. Se você passar uma URL http://, a ponte a rejeita com Worker URL must use HTTPS antes de enviar qualquer requisição.

Passo 2 — Monte o renderizador

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use NextPDF\Cloudflare\CloudflareHtmlRenderer;

$httpFactory = new HttpFactory();

$renderer = new CloudflareHtmlRenderer(
    config:          $config,
    httpClient:      new Client(),     // PSR-18 ClientInterface
    requestFactory:  $httpFactory,     // PSR-17 RequestFactoryInterface
    streamFactory:   $httpFactory,     // PSR-17 StreamFactoryInterface
    logger:          null,             // optional PSR-3 LoggerInterface
    responseFactory: $httpFactory,     // PSR-17; enables the pinned transport
);

O construtor exige quatro argumentos: a config, o cliente PSR-18, a request factory e a stream factory. Outros quatro argumentos são opcionais: o logger, a factory do renderizador local, uma política de segurança HTML explícita e a response factory. Ao fornecer a response factory, você habilita o transporte fixado de Client URL (cURL) se houver um conjunto resolvido de Internet Protocol (IP) ou um conjunto de pins Subject Public Key Info (SPKI) presente (veja /integrations/cloudflare/security-and-operations/).

Passo 3 — Renderize e grave

use NextPDF\Cloudflare\Exception\CloudflareNotAvailableException;
use NextPDF\Cloudflare\Exception\CloudflareRenderException;

try {
    $result = $renderer->render('<h1>Hello from the edge</h1>');

    if (!$result->isValid()) {
        throw new RuntimeException('Worker did not return a valid PDF');
    }

    file_put_contents('output.pdf', $result->pdfData);
    printf("Wrote %d bytes from edge %s in %.1f ms\n",
        $result->size(),
        $result->renderLocation !== '' ? $result->renderLocation : 'unknown',
        $result->renderTimeMs,
    );
} catch (CloudflareRenderException $e) {
    // Worker answered but the render failed (HTTP error or malformed body).
    fwrite(STDERR, 'Render failed: ' . $e->getMessage() . PHP_EOL);
    exit(1);
} catch (CloudflareNotAvailableException $e) {
    // Worker unreachable and no usable fallback.
    fwrite(STDERR, 'Edge unavailable: ' . $e->getMessage() . PHP_EOL);
    exit(2);
}

render() usa por padrão a largura A4 (595.28 pontos PDF) e a altura detectada automaticamente (heightPt: 0). Os dois tipos de exceção são separados de propósito. CloudflareRenderException é uma falha do lado do Worker e não é repetida com um fallback. CloudflareNotAvailableException significa que a edge não pôde ser alcançada e nenhum fallback local estava disponível.

Passo 4 — Inspecione o resultado

CloudflareRenderResult é final readonly. Os campos abaixo são preenchidos a partir dos headers da resposta no caminho binário ou dos campos JavaScript Object Notation (JSON) no caminho JSON.

Membro	Origem
pdfData	Bytes brutos do PDF
widthPt	A largura que você solicitou
heightPt	X-Pdf-Height-Pt header / JSON heightPt; usa como padrão 841.89 (altura A4) quando ausente ou não positivo
contentHeightPx	X-Content-Height-Px / JSON contentHeightPx
renderLocation	Derivado do sufixo do header CF-Ray (caminho binário) ou JSON renderLocation
renderTimeMs	X-Render-Time-Ms / JSON renderTimeMs
size()	strlen($pdfData)
isValid()	true quando os bytes começam com %PDF

Opcional — tamanho de papel, fontes e CSS personalizados

$result = $renderer->render(
    html:     '<div style="font-family: NotoSansCJK;">繁體中文文件</div>',
    widthPt:  595.28,
    heightPt: 841.89,           // explicit A4; 0 lets the Worker auto-detect
    fontFiles: ['NotoSansCJKtc-Regular.ttf'],
);

fontFiles só faz sentido quando a config define r2FontBucket. Nesse caso, o payload carrega o nome do bucket e os caminhos dos arquivos de fonte solicitados para que o Worker possa carregá-los.

Opcional — sondagem de disponibilidade

if ($renderer->isAvailable()) {
    $result = $renderer->render($html);
}

isAvailable() envia um HTTP HEAD autenticado para a URL do Worker. Ele retorna true quando o status é inferior a 500. Ele retorna false sem lançar exceção quando a config é inválida ou a requisição falha. Trate isso como um indício, não como uma garantia. O Worker ainda pode falhar no POST subsequente.

Veja também

• /integrations/cloudflare/production-usage/ — conexão de fallback, telemetria e arquivamento em R2.
• /integrations/cloudflare/troubleshooting/ — cada falha mapeada para a respectiva exceção e mensagem.
• /integrations/cloudflare/configuration/ — referência completa dos campos.