Configuration de NextPDF Gotenberg

En bref

La configuration est répartie en deux endroits. Le premier est l’objet-valeur immuable GotenbergConfig, qui décrit le service et ses limites. Le second est le constructeur GotenbergBridge, qui relie les collaborateurs HTTP PSR. Les deux reposent sur l’injection explicite par constructeur. Le paquet ne contient aucun état global, ne lit aucune variable d’environnement en interne et ne cache aucun point de terminaison par défaut.

L’objet de configuration

GotenbergConfig est un objet-valeur final readonly. Construis-le directement avec des arguments nommés ou à partir d’un tableau associatif avec GotenbergConfig::fromArray().

Champs

Champ	Type	Valeur par défaut	Effet
apiUrl	string	''	URL de base du service Gotenberg. Obligatoire : une valeur vide invalide la configuration et fait échouer immédiatement chaque conversion. Doit être en HTTPS.
timeout	int	30	Délai strict de transfert en secondes. Appliqué par le transport épinglé via cURL lorsque ce transport est sélectionné.
maxFileSize	int	52_428_800	Taille maximale en entrée, en octets (50 Mio). Les entrées plus volumineuses sont rejetées avant toute requête.
apiKey	string	''	Jeton porteur (bearer). Lorsqu’il n’est pas vide, il est envoyé dans un en-tête Authorization: Bearer <token>. Marqué #[\SensitiveParameter] afin d’être masqué dans les traces de pile.
pinnedPublicKeys	list<string>	[]	Épingles SPKI TLS primaires sous la forme sha256/<base64>. Une valeur vide désactive l’épinglage.
backupPublicKeys	list<string>	[]	Épingles SPKI TLS de secours, conservées séparément pour que la rotation puisse être validée indépendamment.

Construction directe

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    maxFileSize: 20 * 1024 * 1024,
    apiKey: $secretFromYourSecretStore,
);

Construction à partir d’un tableau

fromArray() accepte les clés en snake_case et ignore tout ce qui est mal formé plutôt que de lever une exception. Une valeur api_url non textuelle devient ''. Un timeout non entier revient à 30. Un max_file_size non entier revient à la valeur par défaut de 50 Mio. Les listes d’épingles qui ne sont pas des tableaux deviennent []. Les entrées non textuelles contenues dans les tableaux d’épingles sont écartées.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Cette analyse tolérante est délibérée. Elle te permet d’injecter directement un tableau de configuration de framework sans couche de pré-validation, tout en produisant un objet correctement typé. Elle ne vérifie pas que l’URL est joignable ni que les épingles sont correctes. Ces contrôles ont lieu au moment de la conversion.

Validité

isValid() renvoie true uniquement lorsque apiUrl est une chaîne non vide. La méthode n’effectue aucun contrôle réseau ni aucun contrôle de schéma. Le filtrage HTTPS et le filtrage des adresses privées se produisent à l’intérieur de la politique de sécurité au moment de la conversion. Avec une configuration invalide, convertFile() et convertString() lèvent une GotenbergConvertException avec le message Invalid Gotenberg configuration: apiUrl is empty. Une configuration invalide fait aussi que isAvailable() renvoie false sans aucun appel réseau.

Le constructeur du pont

GotenbergBridge reçoit la configuration ainsi que les collaborateurs PSR :

Argument	Type	Obligatoire	Effet
config	GotenbergConfig	oui	Le descripteur de service et les limites décrits ci-dessus.
httpClient	Psr\Http\Client\ClientInterface	oui	Le client PSR-18 utilisé pour la sonde de santé et comme transport de repli.
requestFactory	Psr\Http\Message\RequestFactoryInterface	oui	Construit la requête PSR-7.
streamFactory	Psr\Http\Message\StreamFactoryInterface	oui	Construit le flux du corps de la requête.
logger	Psr\Log\LoggerInterface|null	non (par défaut null)	Lorsqu’il est fourni, une entrée de niveau debug est journalisée pour chaque requête de conversion.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	non	Par défaut, il s’agit de la politique de sécurité HTML du cœur. Politique de la couche d’analyse, complémentaire de la politique de la couche de transport.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	non (par défaut null)	Obligatoire pour activer le transport épinglé via cURL. Sans ce paramètre, le pont utilise toujours le client PSR-18 injecté.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    logger: $psrLogger,
    responseFactory: $psrResponseFactory,
);

Sélection du transport

Le pont possède deux transports et en choisit un pour chaque requête de conversion :

• Transport épinglé via cURL — utilisé lorsqu’un responseFactory a été injecté et qu’il y a quelque chose à épingler (l’URL a été résolue en une ou plusieurs adresses IP, ou des épingles SPKI sont configurées). Ce transport lie l’ensemble des adresses résolues avec CURLOPT_RESOLVE. Il impose l’épinglage SPKI avec CURLOPT_PINNEDPUBLICKEY lorsque des épingles sont présentes. Il vérifie le pair TLS et l’hôte (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Il applique le délai d’attente configuré et désactive le suivi des redirections (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Client PSR-18 injecté — utilisé dans tous les autres cas, y compris lorsque l’URL de l’API est un littéral d’adresse IP publique nu (aucun DNS à épingler) et qu’aucune épingle SPKI n’est configurée, ou lorsqu’aucun responseFactory n’a été fourni.

La conséquence pratique : pour obtenir des connexions résistantes au DNS-rebinding avec épinglage TLS, injecte un responseFactory et configure des épingles. La sonde de santé utilise toujours le client PSR-18 injecté, quelle que soit la sélection du transport.

Épinglage de clé publique TLS

L’épinglage suit le modèle d’empreinte SPKI SHA-256. Chaque épingle est une chaîne de la forme sha256/<base64-encoded-spki-hash>. Le transport accepte aussi la forme native de cURL sha256//<base64> et convertit vers celle-ci la forme à une seule barre oblique. Tout autre préfixe lève une InvalidSpkiPinException.

allPublicKeyPins() renvoie l’union sans doublons de pinnedPublicKeys et de backupPublicKeys. La couche TLS accepte un certificat dont l’empreinte SPKI correspond à n’importe quel membre de cet ensemble combiné. Sur le plan opérationnel, tu devrais configurer au moins une épingle de secours afin qu’une rotation planifiée de certificat ou de clé ne coupe pas le pont du service pendant la propagation de la nouvelle clé. Conserver la liste de secours séparée de la liste primaire te permet de valider et d’effectuer la rotation de l’épingle de secours indépendamment de l’épingle active. Consulte /integrations/gotenberg/security-and-operations/ pour la procédure de rotation.

Options de conversion par requête

Le type de charge utile multipart (GotenbergConvertPayload) contient deux options de conversion Gotenberg facultatives en plus du fichier :

• landscape (bool, par défaut false) — envoyé comme champ de formulaire landscape, "true" ou "false".
• nativePageRanges (string, par défaut '') — envoyé comme champ de formulaire nativePageRanges uniquement lorsqu’il n’est pas vide ; accepte la syntaxe de plages de Gotenberg telle que 1-3 ou 1,3,5-9.

Les points d’entrée publics convertFile() et convertString() construisent la charge utile avec les valeurs par défaut de ces deux champs. Ces champs font partie du contrat de charge utile et sont couverts par la suite de tests. Expose-les depuis ta propre couche d’intégration si tu as besoin d’une sortie en mode paysage ou d’une sélection de pages.

Voir aussi

• /integrations/gotenberg/install/ — installation et base Gotenberg.
• /integrations/gotenberg/quickstart/ — un exemple exécutable de bout en bout.
• /integrations/gotenberg/production-usage/ — provenance de la configuration, secrets, délais d’attente, nouvelles tentatives.
• /integrations/gotenberg/security-and-operations/ — le modèle de sécurité complet et la rotation des épingles.
• /integrations/gotenberg/troubleshooting/ — ce que signifie chaque exception liée à la configuration.