NextPDF Cloudflare : démarrage et découverte

En bref

Le pont ne fournit aucun service provider, bundle ou hook d’auto-découverte qui lui soit propre. Il s’agit d’un ensemble de classes final dotées de constructeurs explicites. Ici, la « découverte » consiste à décider quels collaborateurs injecter et à les enregistrer dans le conteneur de ton framework. Cette page décrit ce câblage. Elle n’introduit aucun mécanisme d’enregistrement que le paquet ne possède pas.

Comment le pont de rendu est découvert

Tu construis CloudflareHtmlRenderer ; il n’est pas découvert automatiquement. Ses dépendances sont des interfaces PSR-18, PSR-17 et PSR-3, auxquelles s’ajoutent les types de configuration et les contrats propres au paquet. Tout framework capable de construire ces collaborateurs peut construire le moteur de rendu. Comme le paquet ne dépend que de contrats PSR — le test tests/Unit/Architecture/PsrConformanceTest.php garantit qu’il n’existe aucun couplage à un client concret —, ton application hôte réutilise sans modification son enregistrement de client HTTP existant. Les adaptateurs NextPDF pour Laravel, Symfony et CodeIgniter réutilisent ce même enregistrement PSR-18. Ce paquet n’ajoute aucun paquet propre à un framework.

Séquence de démarrage

Résous les éléments dans cet ordre, comme le reflète le constructeur de CloudflareHtmlRenderer :

1. Résous un ClientInterface PSR-18 (l’enregistrement de client HTTP existant de l’application).
2. Résous les RequestFactoryInterface et StreamFactoryInterface PSR-17 ; résous aussi ResponseFactoryInterface lorsque le transport cURL épinglé est souhaité.
3. Construis un CloudflareRendererConfig à partir de la configuration résolue (voir « Ordre de résolution de la configuration »).
4. Résous éventuellement un LoggerInterface PSR-3, un LocalRendererFactoryInterface et un HtmlSecurityPolicyInterface explicite.
5. Construis CloudflareHtmlRenderer avec les éléments précédents.

Aucune de ces étapes ne contacte le réseau. La première interaction réseau a lieu lors du premier appel à render() ou à isAvailable().

Enregistrements dans le conteneur

Voici un enregistrement représentatif (pseudo-code indépendant du 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),
    );
});

Ordre de résolution de la configuration

Le paquet ne lit pas lui-même les variables d’environnement. Il accepte un CloudflareRendererConfig déjà constitué. Dans l’application hôte, l’ordre de résolution recommandé est le suivant : d’abord les variables d’environnement, puis la configuration publiée ou fournie par le framework, puis les valeurs par défaut du paquet intégrées au constructeur (documentées dans /integrations/cloudflare/configuration/). CloudflareRendererConfig::fromArray() applique les valeurs par défaut du constructeur pour toute clé absente ou mal typée ; ainsi, un tableau de configuration partiel utilise des replis prévisibles au lieu d’échouer.

Diagnostics

Le signal de démarrage est CloudflareRendererConfig::isValid() — une vérification pure qui confirme que workerUrl et apiToken sont tous deux non vides, sans appel réseau, ce qui convient à une barrière de déploiement. Le signal d’exécution est CloudflareHtmlRenderer::isAvailable(), une requête HTTP HEAD authentifiée qui renvoie true pour un statut inférieur à 500 et false dans le cas contraire (sans jamais lever d’exception), ce qui convient à une sonde de disponibilité. Une sonde réussie reste un indice, pas une garantie : la requête POST qui suit peut tout de même échouer.

Voir aussi

• /integrations/cloudflare/integration/ — le guide d’intégration de bout en bout.
• /integrations/cloudflare/overview/ — ce qu’est le pont et la frontière qu’il franchit.
• /integrations/cloudflare/configuration/ — chaque champ et sa valeur par défaut.
• /integrations/cloudflare/security-and-operations/ — quand le transport épinglé s’active.