Configurer le pont Cloudflare de NextPDF

En un coup d’œil

Trois objets de configuration immuables régissent le paquet. Chaque valeur par défaut indiquée sur cette page est lue depuis la signature de constructeur correspondante dans src/Cloudflare/. Elle ne provient ni d’une spécification ni d’une estimation. Lorsqu’un maximum est indiqué, il s’agit d’une limite que ce paquet applique. Ce n’est pas une affirmation sur la capacité de la plateforme Cloudflare.

CloudflareRendererConfig

Configuration du moteur de rendu. final readonly. Construis-la directement ou via CloudflareRendererConfig::fromArray().

Champ	Type	Valeur par défaut	Signification
workerUrl	string	— (requis)	URL du point de terminaison du Worker. Doit utiliser HTTPS.
apiToken	string	— (requis)	Jeton Bearer. Marqué #[SensitiveParameter].
renderTimeout	int	30	Délai d’expiration du transfert, en secondes, appliqué par le transport cURL épinglé.
defaultCss	string	''	CSS injecté dans la charge utile avant ton HTML.
maxHtmlSize	int	5000000	Taille maximale de l’entrée HTML, en octets, appliquée avant l’envoi de la requête.
r2FontBucket	?string	null	Nom du bucket R2 destiné aux paquets de polices personnalisés.
fallbackToLocal	bool	true	Indique si, quand le Worker est injoignable, le rendu bascule vers un moteur de rendu local.
pinnedPublicKeys	list<string>	[]	Empreintes SPKI SHA-256, au format sha256/<base64>.
backupPublicKeys	list<string>	[]	Pins SPKI de secours, conservés séparément afin que la rotation soit validée indépendamment.

isValid() renvoie true uniquement lorsque workerUrl !== '' et apiToken !== ''. allPublicKeyPins() renvoie l’union dédupliquée de pinnedPublicKeys et backupPublicKeys. La couche TLS accepte un certificat dont le hachage SPKI apparaît dans l’un des membres de cette union. Cela correspond à RFC 7469 §2.6, qui valide une connexion épinglée lorsque l’ensemble des empreintes SPKI présentées intersecte l’ensemble épinglé. RFC 7469 §2.5 décrit le pin de secours comme le principal mécanisme de récupération en cas d’échec involontaire de validation du pin. Conserve au moins un pin de secours afin qu’une rotation de certificat ne casse pas le point de terminaison — voir /integrations/cloudflare/security-and-operations/.

fromArray() correspondance des clés

CloudflareRendererConfig::fromArray() lit les clés en snake_case et applique les mêmes valeurs par défaut si une clé est absente ou si son type est incorrect :

Clé du tableau	Correspond à
worker_url	workerUrl
api_token	apiToken
render_timeout	renderTimeout (par défaut 30)
default_css	defaultCss
max_html_size	maxHtmlSize (par défaut 5000000)
r2_font_bucket	r2FontBucket
fallback_to_local	fallbackToLocal (par défaut true)
pinned_public_keys	pinnedPublicKeys (les membres qui ne sont pas des chaînes sont écartés)
backup_public_keys	backupPublicKeys (les membres qui ne sont pas des chaînes sont écartés)

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => 'https://pdf-renderer.example.workers.dev/render',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => 'pdf-fonts',
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Limites de taille d’entrée appliquées par le paquet

Ces limites sont appliquées par CloudflareSecurityPolicy::validate() avant qu’une requête ne quitte le processus. Les nombres proviennent de la source :

Limite	Valeur	Où
Entrée HTML maximale	maxHtmlSize (par défaut 5000000 octets)	CloudflareSecurityPolicy::validate()
Taille maximale d’URI de données base64 décodée	13631488 octets (≈13 Mo)	CloudflareSecurityPolicy::MAX_DATA_URI_BYTES

Dépasser l’une ou l’autre déclenche une RuntimeException avec un message indiquant la taille fautive et la limite. Le plafond base64 protège contre les bombes de décompression. La politique estime la taille décodée à partir de la longueur base64 et rejette la requête dès que ce plafond est atteint ou dépassé. Une balise <meta http-equiv="refresh"> est également rejetée, sans distinction de casse, car elle peut provoquer une redirection depuis l’intérieur de la page rendue.

Le paquet n’énonce que les limites qu’il applique lui-même. Il ne formule aucune affirmation sur les plafonds de requête, de CPU ou de mémoire propres au Worker. Consulte la documentation officielle de Cloudflare et l’implémentation de ton Worker pour ces plafonds.

ApiProtectionConfig

Configuration de la couche optionnelle de protection qu’un Worker — ou une passerelle PHP placée devant lui — applique aux requêtes de rendu entrantes. final readonly.

Champ	Type	Valeur par défaut	Signification
maxRequestsPerMinute	int	60	Plafond de requêtes par client et par minute.
maxRequestsPerHour	int	1000	Plafond de requêtes par client et par heure.
maxPayloadSizeBytes	int	10485760	Charge utile entrante maximale (≈10 Mo).
allowedOrigins	list<string>	[]	Liste d’autorisation CORS. Une liste vide signifie qu’aucune restriction d’origine n’est exprimée ici.
requireApiKey	bool	true	Indique si une clé d’API est requise.
apiKeyHeader	string	'X-Api-Key'	En-tête transportant la clé d’API.
rateLimitWindowSeconds	int	60	Durée, en secondes, de la fenêtre par minute.

fromArray() lit max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header et rate_limit_window_seconds. isValid() exige que chaque champ numérique soit positif et que apiKeyHeader soit non vide.

R2ArchiveConfig

Configuration de l’archivage des PDF rendus vers Cloudflare R2 via l’API compatible S3. final readonly.

Champ	Type	Valeur par défaut	Signification
bucketName	string	— (requis)	Bucket R2. Validé selon la règle de nommage S3.
accountId	string	— (requis)	Identifiant de compte Cloudflare, utilisé pour construire le point de terminaison par défaut.
accessKeyId	string	— (requis)	Identifiant de clé d’accès R2. #[SensitiveParameter].
secretAccessKey	string	— (requis)	Clé d’accès secrète R2. #[SensitiveParameter].
endpoint	string	''	Point de terminaison S3 personnalisé. S’il est vide, la valeur par défaut est construite à partir de accountId.
pathPrefix	string	'pdfs/'	Préfixe de clé pour les objets téléversés.
maxFileSizeBytes	int	104857600	Taille de téléversement maximale (≈100 Mo), appliquée avant le téléversement.

Le constructeur rejette un bucketName non vide qui ne respecte pas la règle compatible S3. Cette règle impose : de 3 à 63 caractères, uniquement des caractères alphanumériques minuscules et des traits d’union, avec un début et une fin par un caractère alphanumérique. Une violation déclenche InvalidArgumentException. isValid() exige que bucketName, accountId, accessKeyId et secretAccessKey soient non vides. Lorsque endpoint est vide, getEndpoint() renvoie https://<accountId>.r2.cloudflarestorage.com.

Gestion des secrets

apiToken, accessKeyId et secretAccessKey portent l’attribut #[SensitiveParameter], si bien que PHP les masque dans les traces de pile. Fournis-les via des variables d’environnement ou un gestionnaire de secrets. Ne les committe jamais. Les objets de configuration sont immuables : une fois définie, une valeur ne peut pas être modifiée après la construction.

Voir aussi

• /integrations/cloudflare/quickstart/ — applique cette configuration lors d’un premier rendu.
• /integrations/cloudflare/production-usage/ — bascule, archivage R2 et protection de l’API configurés ensemble.
• /integrations/cloudflare/security-and-operations/ — épinglage, défense SSRF et rotation des secrets.