Guide développeur Gotenberg

En bref

Le package Gotenberg délègue la conversion à un service externe. Dans le code applicatif, rends la frontière de service explicite : valide l’entrée, construis une charge utile, envoie la requête, analyse le résultat et gère l’échec du service.

Utilise ce guide lorsque tu construis des workflows de conversion de documents bureautiques vers PDF, des points de terminaison d’upload, des contrôles d’état du service ou une politique de transport autour de nextpdf/gotenberg.

Frontière architecturale

Couche	Détenue par	Responsabilité	À ne pas mettre ici
Upload ou source du document	Application	Autorise l’appelant, valide la source et choisis la politique de conversion.	Décisions liées à l’URL du service ou à l’épinglage du transport.
Détection de format	`nextpdf/gotenberg`	Mappe les extensions sûres vers `OfficeFormat`.	Confiance accordée au MIME sans validation applicative.
Pont	`nextpdf/gotenberg`	Construit la requête multipart, appelle Gotenberg et analyse la réponse PDF.	Requêtes métier ou politique de stockage.
Service Gotenberg	Déploiement	Convertit le document bureautique en PDF.	Autorisation applicative PHP.
Moteur principal	`nextpdf/nextpdf`	Importe ou combine éventuellement les données PDF converties.	Conversion bureautique.

Cycle de vie d’exécution

Étape	Comportement	Action du développeur
Création de la configuration	L’URL de l’API, le timeout, la taille maximale, la clé d’API et les pins sont chargés.	Garde l’URL du service et le jeton hors du code source.
Validation de l’entrée	Le chemin du fichier, la taille du fichier, le nom de fichier, l’extension et la sûreté de l’URL sont vérifiés.	Rejette les entrées non prises en charge avant l’envoi.
Construction de la charge utile	`GotenbergConvertPayload` construit les données de formulaire multipart.	Conserve le nom de fichier d’origine uniquement lorsque c’est sûr.
Requête de service	Le pont envoie la requête vers `/forms/libreoffice/convert`.	Configure le timeout et la politique de transport.
Analyse du résultat	`GotenbergResponseParser::parse()` renvoie les octets du PDF et les métadonnées.	Traite les réponses non-PDF ou d’erreur comme des échecs de conversion.

Structure applicative recommandée

Chemin	Rôle
`app/Pdf/Conversion/*`	Wrapper applicatif autour de `GotenbergBridge`.
`app/Pdf/Uploads/*`	Validation de l’upload, stockage et politique de nom de fichier.
`app/Pdf/ConversionPolicy/*`	Politique de taille, de format et de sélection du service.
`tests/Pdf/Conversion/*`	Tests de format, de fichier, de service et de transport.

Garde la validation des fichiers séparée de la conversion. Un service de conversion doit recevoir une entrée déjà autorisée, tout en continuant à s’appuyer sur la validation du package comme défense en profondeur.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

        if (!$result->isValid()) {
            throw new RuntimeException('The conversion service did not return a valid PDF.');
        }

        return $result->pdfData;
    }
}

Modes de conversion

Schéma	API	À utiliser quand	Contrainte
Convertir un chemin de fichier	`GotenbergBridge::convertFile()`	Le document est déjà stocké sur le disque.	Le chemin doit être lisible et approuvé par la politique.
Convertir des octets en mémoire	`GotenbergBridge::convertString()`	L’application dispose déjà des octets issus d’un upload ou d’un magasin d’objets.	Le nom de fichier détermine toujours la détection du format.
Construire la charge utile directement	`GotenbergConvertPayload`	Des tests ou un code de transport personnalisé ont besoin des octets multipart.	La génération de la boundary doit rester indépendante de l’entrée utilisateur.
Analyser la réponse directement	`GotenbergResponseParser::parse()`	Un appel HTTP personnalisé veut tout de même utiliser l’analyse du package.	Doit transmettre le `OfficeFormat` attendu.

Santé et disponibilité

GotenbergBridge::isAvailable() est un signal de disponibilité. Cela ne doit pas être le seul garde-fou à l’exécution. Un service peut répondre au contrôle de disponibilité, puis échouer lors de la conversion suivante.

Contrôle	Rôle	Note opérationnelle
Validité de la configuration	Détecter une URL d’API manquante.	À exécuter au démarrage de l’application ou lors des contrôles de déploiement.
`/health` disponibilité	Détecter un service joignable.	À utiliser pour les tableaux de bord de disponibilité.
Conversion d’une petite fixture	Détecter un LibreOffice défaillant ou une régression du service.	À exécuter dans des smoke tests planifiés, pas à chaque requête.
Surveillance du timeout	Détecter la lenteur du service.	Suivre par format et par taille de fichier.

Points d’extension

Point d’extension	À utiliser pour	Contrainte
PSR-18 `ClientInterface`	Comportement personnalisé du client HTTP.	Doit respecter la sémantique response/exception de PSR-18.
Fabriques PSR-17	Création de requêtes et de flux.	Requises pour la construction du pont.
`HtmlSecurityPolicyInterface`	Politique de la couche d’analyse pour les entrées HTML.	Complète la politique de sécurité de Gotenberg.
`ResponseFactoryInterface`	Construction de la réponse pour le transport cURL épinglé.	Requis seulement quand tu utilises le chemin de transport du package.
`GotenbergSecurityPolicy`	Validation de l’URL, de la taille du fichier, du nom de fichier et des pins.	Garde l’autorisation applicative hors de cette couche.

Workflow de développement

Commence par convertString() dans les tests pour que les fixtures soient explicites.
Ajoute convertFile() seulement après avoir maîtrisé les chemins du système de fichiers.
Maintiens la taille maximale de fichier en dessous des limites du service et de l’infrastructure.
Utilise isAvailable() pour les signaux de disponibilité, pas comme un remplacement de la gestion des erreurs.
Journalise le nom de fichier, le format, la taille, le statut et la durée. Ne journalise pas les octets du document.
Ajoute des tests sur le timeout et les modes d’échec avant d’exposer les points de terminaison d’upload.

Gestion des échecs

Échec	Où le gérer	Réponse recommandée
Extension non prise en charge	Détection de format.	Rejeter avant l’envoi au service.
Nom de fichier non sûr	Politique de sécurité.	Rejeter et normaliser la politique de nommage des uploads.
Fichier trop volumineux	Politique d’upload et validation du package.	Rejeter avant de lire ou d’envoyer des charges utiles volumineuses.
Gotenberg indisponible	Frontière du pont.	Renvoyer une erreur applicative réessayable lorsque c’est approprié.
Réponse non-PDF	Analyseur de réponse.	Traiter comme un échec de conversion et capturer le statut du service.
Échec de validation du pin ou de l’URL	Politique de transport.	Échouer en mode fermé et alerter les opérateurs.

Valeurs par défaut sûres

Aspect	Valeur par défaut	Quand la remplacer
Timeout	`30` secondes.	À augmenter seulement après avoir mesuré la latence réelle du service.
Taille maximale de fichier	`52,428,800` octets.	À abaisser pour les points de terminaison publics ou multi-tenants.
Clé d’API	Vide.	À définir pour les déploiements Gotenberg privés.
Formats pris en charge	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	Ajoute des formats uniquement lorsque `OfficeFormat` et l’analyseur les prennent en charge.
Jeux de pins	Vide.	Ajoute des pins avec des pins de secours et une procédure de rotation.

Liste de contrôle des tests

Les tests de format couvrent les extensions prises en charge et non prises en charge.
Les tests de fichier couvrent les fichiers manquants, illisibles ou trop volumineux, ainsi que les noms de fichiers non sûrs.
Les tests de service couvrent les réponses non-2xx, les corps de réponse invalides et les exceptions de transport.
Les tests de sécurité couvrent les URL de service privées ou invalides lorsque la politique les interdit.
Les tests de timeout vérifient que le timeout configuré est transmis au transport.
Les tests de fixtures gardent les documents d’exemple petits et non sensibles.