Arranque y descubrimiento en NextPDF Cloudflare

Visión general

El puente no incluye proveedor de servicios, bundle ni hook de descubrimiento automático propios. Es un conjunto de clases final con constructores explícitos. Aquí, «descubrimiento» significa decidir qué colaboradores inyectar y registrarlos en el contenedor del framework. Esta página describe ese cableado. No inventa un mecanismo de registro que el paquete no ofrece.

Cómo se descubre el puente de renderizado

Se construye CloudflareHtmlRenderer; no se descubre. Sus dependencias son interfaces de PSR-18, PSR-17 y PSR-3, además de los tipos de configuración y contrato propios del paquete. Cualquier framework capaz de construir esos colaboradores puede construir el renderizador. Como el paquete depende únicamente de contratos PSR —la prueba tests/Unit/Architecture/PsrConformanceTest.php verifica que no hay acoplamiento con un cliente concreto—, la aplicación anfitriona reutiliza sin cambios su enlace de cliente HTTP existente. Los adaptadores de NextPDF para Laravel, Symfony y CodeIgniter reutilizan ese mismo enlace PSR-18. Este paquete no añade ningún paquete específico de framework.

Secuencia de arranque

Resolver los elementos en este orden, reflejando el constructor de CloudflareHtmlRenderer:

1. Resolver un ClientInterface de PSR-18 (el enlace de cliente HTTP existente de la aplicación).
2. Resolver RequestFactoryInterface y StreamFactoryInterface de PSR-17; resolver también ResponseFactoryInterface cuando se desee el transporte cURL fijado.
3. Construir un CloudflareRendererConfig a partir de la configuración resuelta (véase «Orden de resolución de la configuración»).
4. Opcionalmente, resolver un LoggerInterface de PSR-3, un LocalRendererFactoryInterface y un HtmlSecurityPolicyInterface explícito.
5. Construir CloudflareHtmlRenderer con lo anterior.

Ningún paso contacta con la red. La primera interacción de red se produce en la primera llamada a render() o en la primera llamada a isAvailable().

Enlaces del contenedor

Un enlace representativo (pseudocódigo independiente del 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),
    );
});

Orden de resolución de la configuración

El paquete no lee variables de entorno por sí mismo. Acepta un CloudflareRendererConfig completamente formado. En la aplicación anfitriona, el orden de resolución recomendado es: primero, las variables de entorno; después, la configuración publicada o del framework; y, por último, los valores predeterminados del paquete integrados en el constructor (documentados en /integrations/cloudflare/configuration/). CloudflareRendererConfig::fromArray() aplica los valores predeterminados del constructor a cualquier clave ausente o con un tipo incorrecto, de modo que un array de configuración parcial se degrada de forma predecible en lugar de fallar.

Diagnóstico

La señal en el momento del arranque es CloudflareRendererConfig::isValid(): una comprobación pura de que tanto workerUrl como apiToken no están vacíos, sin ninguna llamada de red, por lo que resulta adecuada para una puerta de despliegue. En tiempo de ejecución, la señal es CloudflareHtmlRenderer::isAvailable(), un HEAD HTTP autenticado que devuelve true para un estado inferior a 500 y false (sin lanzar nunca una excepción) en caso contrario; por ello, resulta adecuada para una sonda de disponibilidad. Que la sonda pase es una pista, no una garantía: el POST posterior aún puede fallar.

Véase también

• /integrations/cloudflare/integration/ — el recorrido de integración de extremo a extremo.
• /integrations/cloudflare/overview/ — qué es el puente y el límite que cruza.
• /integrations/cloudflare/configuration/ — cada campo y su valor predeterminado.
• /integrations/cloudflare/security-and-operations/ — cuándo se activa el transporte fijado.