Boot e descoberta no NextPDF Cloudflare

Visão geral

A ponte não inclui service provider, bundle nem hook próprio de descoberta automática. Ela é composta por classes final com construtores explícitos. Aqui, “descoberta” significa escolher os colaboradores que serão injetados e registrá-los no container do framework. Esta página descreve esse encadeamento. Ela não pressupõe um mecanismo de registro que o pacote não oferece.

Como a ponte do renderizador é descoberta

Você constrói o CloudflareHtmlRenderer; você não o descobre. As dependências dele são contratos PHP Standard Recommendation (PSR): PSR-18, PSR-17 e PSR-3, além da configuração e dos tipos de contrato do próprio pacote. Qualquer framework capaz de construir esses colaboradores também pode construir o renderizador. O pacote depende apenas de contratos PSR; o teste tests/Unit/Architecture/PsrConformanceTest.php garante que nenhum cliente concreto fique acoplado ao renderizador. A aplicação hospedeira pode reaproveitar o binding de cliente HTTP existente sem alterações. Os adaptadores NextPDF para Laravel, Symfony e CodeIgniter reaproveitam esse mesmo binding PSR-18. Este pacote não fornece um pacote de framework próprio.

Sequência de boot

Resolva os colaboradores nesta ordem, de acordo com o construtor do CloudflareHtmlRenderer:

1. Resolva a ClientInterface PSR-18 a partir do binding de cliente HTTP já existente na aplicação.
2. Resolva a RequestFactoryInterface e a StreamFactoryInterface PSR-17; resolva também a ResponseFactoryInterface quando você quiser usar o transporte cURL fixado.
3. Construa um CloudflareRendererConfig a partir da configuração resolvida (consulte “Ordem de resolução da configuração”).
4. Opcionalmente, resolva uma LoggerInterface PSR-3, uma LocalRendererFactoryInterface e uma HtmlSecurityPolicyInterface explícita.
5. Construa o CloudflareHtmlRenderer com esses colaboradores.

Nenhuma dessas etapas acessa a rede. A primeira interação de rede acontece quando você chama render() ou isAvailable().

Bindings de container

Um binding representativo (pseudocódigo independente de framework):

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Psr\Log\LoggerInterface;

$container->singleton(CloudflareHtmlRenderer::class, function ($c) {
    return new CloudflareHtmlRenderer(
        config:          CloudflareRendererConfig::fromArray($c->get('config')['cloudflare']),
        httpClient:      $c->get(ClientInterface::class),
        requestFactory:  $c->get(RequestFactoryInterface::class),
        streamFactory:   $c->get(StreamFactoryInterface::class),
        logger:          $c->get(LoggerInterface::class),
        responseFactory: $c->get(ResponseFactoryInterface::class),
    );
});

Ordem de resolução da configuração

O pacote não lê variáveis de ambiente por conta própria. Ele aceita um CloudflareRendererConfig totalmente formado. Na aplicação hospedeira, resolva a configuração nesta ordem: primeiro as variáveis de ambiente, depois a configuração publicada ou do framework e, por fim, os valores padrão do pacote embutidos no construtor (documentados em /integrations/cloudflare/configuration/). CloudflareRendererConfig::fromArray() aplica os valores padrão do construtor para qualquer chave ausente ou com tipo incorreto, de modo que um array de configuração parcial recorra a esses padrões de forma previsível, em vez de falhar.

Diagnóstico

CloudflareRendererConfig::isValid() é o sinal em tempo de boot. É uma verificação pura de que tanto workerUrl quanto apiToken não estão vazios e não faz nenhuma chamada de rede; por isso, você pode usá-la como um gate de deploy. O sinal em tempo de execução é CloudflareHtmlRenderer::isAvailable(), um HEAD HTTP autenticado que retorna true para um status abaixo de 500 e false (sem nunca lançar exceção) caso contrário; por isso, você pode usá-lo como uma sonda de prontidão. Uma sonda bem-sucedida é uma indicação, não uma garantia: o POST subsequente ainda pode falhar.

Veja também

• /integrations/cloudflare/integration/ — o tutorial completo de integração.
• /integrations/cloudflare/overview/ — o que é a ponte e qual limite ela atravessa.
• /integrations/cloudflare/configuration/ — cada campo e valor padrão.
• /integrations/cloudflare/security-and-operations/ — quando o transporte fixado é ativado.