Intégration de Gotenberg avec NextPDF

En bref

Cette page montre comment relier le pont au reste de ton application. Installe-le, branche-le, puis raccorde le PDF converti à un flux de post-traitement NextPDF. Le pont transforme un document Office en PDF ; le flux prend en charge la suite. Cette page est le pendant pratique de /integrations/gotenberg/boot-and-discovery/, qui explique pourquoi le câblage est structuré ainsi.

Installation

composer require nextpdf/gotenberg

Cette commande installe nextpdf/core ^3.0 ainsi que les contrats HTTP PSR. Installe séparément un client PSR-18 et des fabriques PSR-17. Le pont ne dépend que des interfaces : c’est donc à toi de choisir les bibliothèques concrètes. Pour une installation complète, y compris la mise en place du service Gotenberg en HTTPS, consulte /integrations/gotenberg/install/.

Câblage

Construis le pont avec un objet de configuration et les collaborateurs PSR. Injecte également une fabrique de réponses pour activer le transport avec épinglage DNS et épinglage TLS :

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

Le pont exige HTTPS pour l’URL configurée. Il rejette un simple http:// avant toute requête. Exécute Gotenberg derrière une terminaison TLS et pointe le pont vers le point de terminaison HTTPS.

Liaisons du conteneur

Enregistre trois éléments dans ton conteneur hôte. Le premier est le GotenbergConfig, construit à partir de ta source de configuration. Le deuxième est ton client PSR-18, accompagné de tes fabriques PSR-17. Le troisième est GotenbergBridge, câblé avec ces éléments. Ce paquet ne fournit aucune liaison en propre. L’enregistrement natif dans le framework relève des paquets d’intégration de framework dédiés. Consulte /integrations/gotenberg/boot-and-discovery/.

Configuration

Le descripteur de service et ses limites sont tous portés par des champs de GotenbergConfig. Ils couvrent l’URL de l’API, le délai d’expiration, le plafond de taille, le jeton porteur et les empreintes TLS. Les options par requête, landscape et nativePageRanges, sont quant à elles des champs du type de charge utile. /integrations/gotenberg/configuration/ documente chaque champ, avec son type, sa valeur par défaut et son effet.

Raccorder le PDF converti à un flux NextPDF

Un flux de bout en bout typique :

1. Convertis le document Office avec convertFile() ou convertString().
2. Récupère $result->pdfData, qui contient les octets bruts du PDF, et charge-les dans un document NextPDF.
3. Applique un post-traitement, comme l’assemblage de pages, le filigranage, la conversion PDF/A ou les signatures numériques.

L’étape 3 relève de NextPDF, pas du pont. Le paquet nextpdf/premium fournit la signature, les profils PDF/A et le filigranage. Garde la conversion et le post-traitement dans deux étapes distinctes. Tu peux ainsi diagnostiquer chaque défaillance séparément.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

La prise en charge PAdES de l’édition Pro se limite au profil de référence B-B. Elle ne fournit pas B-T, B-LT ni B-LTA. Convertir un document via ce pont n’implique aucune capacité d’horodatage ni de validation à long terme.

Test de fumée

Une fois le câblage terminé, vérifie l’intégration. Tu peux le faire sans convertir un document réel :

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

isAvailable() valide l’URL sans aucun trafic réseau. La méthode envoie ensuite une requête HEAD vers <apiUrl>/health. Convertis ensuite un petit document réputé valide. Cela teste tout le chemin multipart vers <apiUrl>/forms/libreoffice/convert, ainsi que la validation de la réponse.

Points d’entrée de l’API publique

La surface publique utilisée par cette intégration :

• GotenbergConfig — descripteur de service et limites immuables ; fromArray() le construit à partir d’un tableau de configuration.
• GotenbergBridge::convertFile(string $path) — convertit un fichier sur disque.
• GotenbergBridge::convertString(string $bytes, string $fileName) — convertit des octets conservés en mémoire.
• GotenbergBridge::isAvailable() — fournit une sonde de disponibilité sans levée d’exception.
• GotenbergConvertResult — expose pdfData, sourceFormat, isValid() et size().
• GotenbergConvertException — représente le type d’exception de la couche de conversion.

Le contrat complet est décrit dans /integrations/gotenberg/configuration/ et /integrations/gotenberg/troubleshooting/. Il couvre le choix du transport et le catalogue des exceptions.

Voir aussi

• /integrations/gotenberg/boot-and-discovery/ — pourquoi le câblage se présente ainsi.
• /integrations/gotenberg/quickstart/ — une première conversion guidée.
• /integrations/gotenberg/production-usage/ — secrets, nouvelles tentatives, délais d’expiration, observabilité.
• /integrations/gotenberg/install/ — installation du paquet et du service Gotenberg.