Intégration Cloudflare de NextPDF

En bref

Cette page couvre le parcours complet, de bout en bout. Installe le paquet, configure-le, génère un PDF et, si tu le souhaites, archive le résultat. À chaque étape, le rendu NextPDF est piloté via un Cloudflare Worker et R2. Elle complète concrètement la page de concepts /integrations/cloudflare/overview/ et la référence /integrations/cloudflare/configuration/.

Installation

composer require nextpdf/cloudflare:^0.1

Ajoute ensuite un client PSR-18 et des fabriques PSR-17, par exemple Guzzle 7. Le paquet ne déclare que des contrats PSR et ne fournit aucun client concret qui lui soit propre : c’est donc à toi d’en fournir un. Pour plus de détails, consulte /integrations/cloudflare/install/.

Amorçage / découverte automatique

Ce pont n’a ni service provider ni bundle. Construis-le plutôt directement avec des collaborateurs PSR et un CloudflareRendererConfig. Le framework hôte l’enregistre dans son conteneur en réutilisant la liaison PSR-18 déjà présente dans l’application. Pour la séquence d’amorçage complète et un exemple de liaison de conteneur, consulte /integrations/cloudflare/boot-and-discovery/.

Liaisons de conteneur

Enregistre CloudflareHtmlRenderer en singleton. Donne-lui le client PSR-18, les fabriques de requête et de flux PSR-17, ainsi qu’un logger PSR-3 optionnel. Si tu utilises le transport cURL épinglé, fournis-lui aussi une fabrique de réponse PSR-17. Consulte l’exemple de liaison dans /integrations/cloudflare/boot-and-discovery/.

Publier la configuration

Le paquet lit ses réglages depuis un CloudflareRendererConfig. Récupère les secrets depuis l’environnement, jamais depuis des fichiers versionnés :

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => getenv('CF_WORKER_URL') ?: '',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => getenv('CF_R2_FONT_BUCKET') ?: null,
]);

workerUrl doit utiliser HTTPS. apiToken est marqué #[SensitiveParameter]. Pour la référence complète des champs, consulte /integrations/cloudflare/configuration/, qui détaille les champs d’épinglage SPKI ainsi que chaque valeur par défaut. La configuration de l’archivage R2 et la couche de protection de l’API sont détaillées dans /integrations/cloudflare/production-usage/.

Test de fumée du service provider / bundle

Aucun service provider n’est à soumettre à un test de fumée. La vérification d’amorçage équivalente est la suivante :

$config = CloudflareRendererConfig::fromArray($appConfig['cloudflare']);
assert($config->isValid(), 'Cloudflare config incomplete');

// Optional runtime reachability check (authenticated HTTP HEAD):
if (!$renderer->isAvailable()) {
    // Worker not reachable — degrade or alert.
}

isValid() est une simple vérification de complétude, sans aucun appel réseau. La méthode isAvailable() effectue un HEAD authentifié. Elle renvoie false sans lever d’exception lorsque le Worker est indisponible.

Points d’entrée de l’API publique

La surface publique du paquet est entièrement sous NextPDF\Cloudflare\ :

Type	Rôle
`CloudflareHtmlRenderer`	Point d’entrée du rendu : `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Configuration du moteur de rendu (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Résultat de rendu typé (`isValid()`, `size()`).
`CloudflareRenderPayload`	Charge utile JSON du Worker (`toJson()`).
`CloudflareResponseParser`	Analyseur de réponse du Worker → résultat.
`CloudflareSecurityPolicy`	Validation des entrées et des URL.
`Transport\PinnedCurlTransport`	Transport PSR-18 avec DNS épinglé / TLS épinglé.
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Contrats de repli local.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Protection de l’API entrante.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	Archivage R2.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Hiérarchie d’exceptions.

Pour un guide de rendu complet, consulte /integrations/cloudflare/quickstart/. Le câblage de production se trouve dans /integrations/cloudflare/production-usage/ ; il couvre le repli, la télémétrie, l’archivage et la protection.

Voir aussi

/integrations/cloudflare/overview/ — la frontière de confiance et le modèle de rendu en périphérie.
/integrations/cloudflare/quickstart/ — un premier rendu exécutable.
/integrations/cloudflare/boot-and-discovery/ — le câblage détaillé du conteneur.
/integrations/cloudflare/security-and-operations/ — la défense contre les SSRF, l’épinglage et les consignes d’exploitation.
/integrations/cloudflare/troubleshooting/ — les modes de défaillance associés à leurs exceptions.