Boot e discovery per NextPDF Cloudflare

In sintesi

Il bridge non fornisce service provider, bundle o hook di auto-discovery propri. È composto da classi final con costruttori espliciti. In questa pagina, «discovery» significa decidere quali collaboratori iniettare e registrarli nel container del framework. La pagina descrive questo wiring. Non introduce un meccanismo di registrazione che il pacchetto non possiede.

Come avviene la discovery del bridge di rendering

Si costruisce CloudflareHtmlRenderer; non lo si rileva tramite discovery. Dipende da interfacce PSR-18, PSR-17 e PSR-3, oltre che dai tipi di configurazione e dai contratti propri del pacchetto. Qualunque framework in grado di costruire questi collaboratori può costruire il renderer. Poiché il pacchetto dipende solo dai contratti PSR — il test tests/Unit/Architecture/PsrConformanceTest.php asserisce che non esiste alcun accoppiamento a un client concreto — l’applicazione host può riutilizzare senza modifiche il binding del proprio client HTTP esistente. Gli adapter NextPDF per Laravel, Symfony e CodeIgniter riutilizzano lo stesso binding PSR-18. Questo pacchetto non aggiunge un proprio pacchetto di framework.

Sequenza di boot

Risolvere gli elementi in questo ordine, rispecchiando il costruttore di CloudflareHtmlRenderer:

1. Risolvere un ClientInterface PSR-18 (il binding del client HTTP esistente dell’applicazione).
2. Risolvere RequestFactoryInterface e StreamFactoryInterface di PSR-17; risolvere anche ResponseFactoryInterface quando si desidera il trasporto cURL fissato.
3. Costruire un CloudflareRendererConfig a partire dalla configurazione risolta (vedere «Ordine di risoluzione della configurazione»).
4. Risolvere facoltativamente un LoggerInterface PSR-3, un LocalRendererFactoryInterface e un esplicito HtmlSecurityPolicyInterface.
5. Costruire CloudflareHtmlRenderer con gli elementi risolti sopra.

Nessun passaggio effettua chiamate di rete. La prima interazione di rete avviene alla prima chiamata a render() o a isAvailable().

Binding del container

Un binding rappresentativo (pseudocodice indipendente dal 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),
    );
});

Ordine di risoluzione della configurazione

Il pacchetto non legge direttamente le variabili d’ambiente. Accetta un CloudflareRendererConfig già completamente formato. Nell’applicazione host, l’ordine di risoluzione consigliato è: prima le variabili d’ambiente, poi la configurazione pubblicata o quella del framework, infine i valori predefiniti del pacchetto incorporati nel costruttore (documentati in /integrations/cloudflare/configuration/). CloudflareRendererConfig::fromArray() applica i valori predefiniti del costruttore a qualsiasi chiave assente o di tipo errato, in modo che un array di configurazione parziale degradi in modo prevedibile anziché fallire.

Diagnostica

Il segnale al momento del boot è CloudflareRendererConfig::isValid() — una verifica pura che controlla che workerUrl e apiToken siano entrambi non vuoti, senza alcuna chiamata di rete; è quindi adatta a un gate di deploy. Il segnale a runtime è CloudflareHtmlRenderer::isAvailable(), un HEAD HTTP autenticato che restituisce true per uno stato inferiore a 500 e false (senza mai sollevare eccezioni) negli altri casi; è quindi adatto a un probe di readiness. Un probe superato è un indizio, non una garanzia: la POST successiva può comunque fallire.

Vedere anche

• /integrations/cloudflare/integration/ — guida end-to-end all’integrazione.
• /integrations/cloudflare/overview/ — che cos’è il bridge e quale confine attraversa.
• /integrations/cloudflare/configuration/ — tutti i campi e i rispettivi valori predefiniti.
• /integrations/cloudflare/security-and-operations/ — quando attivare il trasporto fissato.