Vue d'ensemble de NextPDF Gotenberg

En bref

NextPDF Gotenberg est un pont léger entre NextPDF et un service externe Gotenberg. Il reçoit un document Office que NextPDF ne peut pas rendre nativement, l’envoie à une instance Gotenberg via HTTP, récupère un PDF en retour et transmet ce PDF à ton application. À partir de là, les autres fonctionnalités de NextPDF prennent le relais pour le post-traitement.

Le paquet est volontairement réduit et explicite. Il n’embarque pas de moteur de rendu, ne lance pas LibreOffice et n’exécute aucun navigateur. Chaque conversion correspond à une seule requête HTTP multipart envoyée à un point de terminaison Gotenberg. C’est toi qui exploites ce point de terminaison et qui indiques son adresse au pont dans la configuration.

Utilise ce pont lorsque tu disposes de fichiers source .docx, .xlsx, .pptx, .odt, .ods ou .odp et que tu veux les convertir en PDF dans un pipeline NextPDF. Tout ce qui intervient une fois le PDF produit — signature, conversion PDF/A, filigrane, fusion — relève de NextPDF lui-même ou du paquet nextpdf/premium.

Ce dont dépend le pont

Le pont a une dépendance d’exécution qui n’est pas un paquet PHP : un service Gotenberg en fonctionnement que le pont peut joindre via HTTPS.

Le pont n’installe pas, ne gère pas et ne supervise pas Gotenberg. C’est toi qui déploies Gotenberg (le projet amont publie une image de conteneur) et qui assumes sa disponibilité, sa capacité et son exposition réseau.
Le pont utilise la route de conversion LibreOffice de Gotenberg. L’URL de la requête est construite sous la forme <apiUrl>/forms/libreoffice/convert, où <apiUrl> correspond à l’URL de base que tu configures. C’est cette route qui détermine pour le pont l’ensemble des formats pris en charge.
La sonde de santé cible <apiUrl>/health avec une requête HTTP HEAD et considère tout statut inférieur à 500 comme disponible.

La conversion se déroule dans un service que tu exploites ; le comportement du pont dépend donc de la version de Gotenberg que tu fais tourner. Le pont envoie une requête multipart de forme fixe, et le chemin de la route (/forms/libreoffice/convert) ainsi que le chemin de santé (/health) sont les seuls éléments du contrat côté Gotenberg qu’il présuppose. Consulte /integrations/gotenberg/install/ pour les bases du déploiement et /integrations/gotenberg/security-and-operations/ pour durcir le service.

Formats de document pris en charge

Le pont convertit strictement les formats énumérés dans son type OfficeFormat. Le format est détecté à partir de l’extension du fichier (sans tenir compte de la casse, et avec tolérance d’un point initial). Il est ensuite envoyé à Gotenberg avec un type MIME fixe :

Format	Extension	Type MIME envoyé à Gotenberg
Word (OOXML)	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel (OOXML)	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint (OOXML)	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

Cette liste est exhaustive. Toute extension en dehors de cet ensemble déclenche une ValueError avant l’émission de la moindre requête réseau, si bien que le pont ne tente jamais une conversion qu’il ne peut pas décrire. Le pont ne prétend pas prendre en charge « tout fichier Office » ni « tous les formats de document ». Il prend en charge les six formats ci-dessus, car ce sont les six que le code reconnaît et que la suite de tests exerce.

Les formats binaires anciens (.doc, .xls, .ppt), le texte enrichi (.rtf), le texte brut, le CSV et les formats d’image ne font pas partie de l’ensemble reconnu par le pont. La route LibreOffice propre à Gotenberg peut accepter une gamme d’entrées plus large. Le pont se limite volontairement à l’ensemble énuméré, afin que la détection du format, le type MIME et les métadonnées du résultat restent toujours cohérents et vérifiables.

Comment se déroule une conversion

Une conversion suit une passe unique et linéaire. Elle valide chaque étape avant qu’un seul octet ne quitte le processus :

La configuration est vérifiée. Une URL d’API vide échoue immédiatement avec une exception de conversion.
L’URL d’API est validée : HTTPS est requis, et l’hôte est résolu puis filtré afin qu’il ne puisse pas pointer vers une adresse privée ou réservée. L’ensemble des adresses résolues est capturé en vue d’un épinglage ultérieur.
L’entrée est lue (pour les conversions depuis un fichier, le chemin est d’abord canonicalisé pour bloquer la traversée) et son extension est mappée vers un OfficeFormat.
La longueur en octets est contrôlée par rapport au maximum configuré, et le nom de fichier est filtré afin de détecter les séquences de traversée, les barres obliques, les octets nuls et les caractères de contrôle.
L’ensemble des adresses est revérifié juste avant la requête afin de combler l’écart entre validation et connexion.
Un corps multipart/form-data est construit et envoyé en POST vers la route LibreOffice, avec un jeton bearer si l’un est configuré.
La réponse est analysée : le statut doit être 200, le Content-Type doit contenir application/pdf, et le corps doit commencer par la signature %PDF. Un résultat n’est renvoyé qu’à cette condition.

Tout échec aux étapes 1 à 7 déclenche une exception typée, au lieu de renvoyer un résultat partiel ou non vérifié. Les exceptions exactes et leurs conditions de déclenchement sont répertoriées dans /integrations/gotenberg/troubleshooting/.

Ce que tu récupères

Une conversion réussie renvoie un objet résultat. Cet objet contient les octets bruts du PDF, le format source qui a été converti et une mesure facultative du temps de rendu. Il expose aussi un contrôle de validité (un corps non vide qui commence par %PDF) ainsi qu’un accesseur de taille en octets. Les octets forment un flux PDF standard ; tu peux donc les écrire sur le disque, les diffuser vers un client ou les transmettre à un document NextPDF pour un traitement ultérieur.

Là où le pont s’arrête

Le pont convertit et valide. Il ne prend pas en charge les opérations suivantes :

Signer, chiffrer, linéariser ou convertir la sortie en PDF/A. Il s’agit de préoccupations de post-traitement prises en charge par le cœur de NextPDF ou par nextpdf/premium.
Réessayer les requêtes échouées, mettre le travail en file d’attente ou mettre les résultats en cache. Ces responsabilités relèvent de l’application. /integrations/gotenberg/production-usage/ montre où les ajouter autour du pont.
Gérer le cycle de vie du service Gotenberg. Le déploiement et l’exploitation sont traités dans /integrations/gotenberg/security-and-operations/.

Éditions et post-traitement

Le cœur OSS peut écrire le PDF converti tel quel. Si tu dois signer le document converti, produire un profil d’archivage PDF/A ou appliquer un filigrane, le paquet nextpdf/premium ajoute ces capacités par-dessus. Le pont lui-même est neutre vis-à-vis de l’édition : il produit un PDF. Ce que tu fais de ce PDF détermine si tu as besoin d’une édition commerciale.

La baseline PAdES disponible dans l’édition Pro est uniquement B-B. Les profils de validation à long terme (B-T, B-LT, B-LTA) ne font pas partie de l’édition Pro et ne sont pas fournis par ce pont. N’en déduis pas une capacité d’horodatage ou de LTV à partir de la présence de ce paquet.

Voir aussi

/integrations/gotenberg/install/ — installe le paquet et mets en place une base Gotenberg.
/integrations/gotenberg/configuration/ — chaque option de configuration, son type, sa valeur par défaut et son effet.
/integrations/gotenberg/quickstart/ — ta première conversion exécutable.
/integrations/gotenberg/production-usage/ — câbler le pont dans une application réelle.
/integrations/gotenberg/troubleshooting/ — le catalogue des exceptions et ce que chacune signifie.
/integrations/gotenberg/security-and-operations/ — le modèle de sécurité et la manière d’exploiter en toute sécurité le service dont tu dépends.
/integrations/gotenberg/boot-and-discovery/ — comment les frameworks hôtes découvrent et câblent le pont.
/integrations/gotenberg/integration/ — piloter le rendu NextPDF via le service.