Installer NextPDF Gotenberg

En bref

L’installation de la passerelle comporte deux volets. Le premier correspond au paquet PHP et à ses dépendances HTTP PSR, que tu installes avec Composer. Le second correspond au service Gotenberg appelé par le paquet. La passerelle effectue la conversion en déléguant le travail à ce service ; elle ne peut donc rien convertir tant qu’une instance Gotenberg n’est pas joignable.

Termine ces deux volets avant d’écrire le moindre code de conversion.

Prérequis

Prérequis	Contrainte	Pourquoi
PHP	>=8.4 <9.0	Le paquet déclare cette plage dans composer.json.
cœur NextPDF	^3.0	Dépendance directe déclarée dans composer.json.
Client HTTP PSR-18	^1.0	La passerelle envoie les requêtes via une instance injectée de Psr\Http\Client\ClientInterface.
Fabriques HTTP PSR-17	^1.1	La passerelle construit les requêtes et les flux via des fabriques PSR-17 injectées.
Journaliseur PSR-3	^3.0 (facultatif)	Un journaliseur peut être injecté pour journaliser les requêtes à des fins de débogage.
Service Gotenberg	Joignable via HTTPS	La conversion est effectuée par le service externe, et non par ce paquet.

La passerelle n’inclut ni client PSR-18 ni fabriques PSR-17. Tu choisis toi-même les implémentations. Par exemple, tu peux associer un client basé sur Guzzle à ses fabriques PSR-17, ou le client HTTP Symfony avec nyholm/psr7. Toute implémentation conforme aux contrats PSR pertinents fonctionne, car la passerelle dépend uniquement des interfaces, et non d’une bibliothèque spécifique.

Étape 1 — installer le paquet

Ajoute le paquet avec Composer :

composer require nextpdf/gotenberg

Cela résout nextpdf/core ^3.0 ainsi que les contrats HTTP PSR : psr/http-client, psr/http-factory et psr/log. Il n’installe pas de client HTTP concret.

Étape 2 — installer un client PSR-18 et des fabriques PSR-17

Installe un client PSR-18 et l’ensemble correspondant de fabriques PSR-17. Avec Guzzle :

composer require guzzlehttp/guzzle guzzlehttp/psr7

Ou avec le client HTTP Symfony et Nyholm PSR-7 :

composer require symfony/http-client nyholm/psr7

La passerelle les reçoit comme arguments de constructeur. Elle n’instancie jamais elle-même un client HTTP. Le choix t’appartient donc entièrement et se fait au moment où tu assembles la passerelle. Consulte /integrations/gotenberg/configuration/ pour la forme du constructeur et /integrations/gotenberg/quickstart/ pour un exemple d’assemblage complet.

Étape 3 — mettre en place un service Gotenberg

La passerelle appelle la route de conversion LibreOffice de Gotenberg ; il te faut donc une instance Gotenberg que la passerelle puisse joindre. Le projet amont publie une image de conteneur. La commande de référence pour le développement local est :

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Cela expose Gotenberg sur le port 3000 en HTTP non chiffré, ce qui convient uniquement au développement local. La passerelle exige HTTPS pour l’URL d’API configurée. Elle rejette le http:// simple avant d’envoyer la moindre requête. Au-delà d’une expérimentation locale, place Gotenberg derrière un proxy inverse ou un maillage de services qui termine TLS, puis pointe la passerelle vers le point de terminaison HTTPS. /integrations/gotenberg/security-and-operations/ décrit le modèle de déploiement en production, l’exposition réseau et l’authentification.

L’étiquette d’image indiquée ici (gotenberg/gotenberg:8) correspond à la ligne majeure amont de Gotenberg. Le README de ce projet et la référence d’intégration de base citent tous deux cette ligne. En production, épingle une étiquette de correctif précise plutôt que de suivre une étiquette majeure mouvante. Vérifie aussi les chemins des routes (/forms/libreoffice/convert, /health) par rapport à la version de Gotenberg que tu déploies. La passerelle suppose l’existence de ces deux chemins et ne fait aucune autre hypothèse sur le service.

Étape 4 — vérifier le câblage

À ce stade, le paquet et un client HTTP sont installés, et Gotenberg est joignable via HTTPS. Avant de tenter une vraie conversion, confirme que le service est visible pour la passerelle à l’aide de la sonde de santé intégrée :

<?php

declare(strict_types=1);

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

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

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

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() valide d’abord l’URL configurée. La méthode renvoie false pour une URL vide, non-HTTPS ou pointant vers une adresse privée, sans émettre le moindre trafic réseau. Elle envoie ensuite une requête HEAD vers <apiUrl>/health et considère le service disponible lorsque le statut est inférieur à 500. Une erreur réseau est interceptée et traduite en indisponibilité, plutôt que levée.

Note de version

Cette documentation décrit le paquet pour sa ligne ^3.0. Cette ligne correspond à l’exigence du composer.json et à la matrice de prise en charge de SECURITY.md, où la 3.x est prise en charge et la 2.x ne l’est pas. Les références 0.x antérieures dans les pages squelettes du dépôt précèdent la ligne 3.0, et la contrainte du composer.json les remplace.

Voir aussi

• /integrations/gotenberg/overview/ — ce que fait la passerelle et les formats qu’elle convertit.
• /integrations/gotenberg/configuration/ — chaque argument de constructeur et champ de configuration.
• /integrations/gotenberg/quickstart/ — une première conversion complète et exécutable.
• /integrations/gotenberg/security-and-operations/ — comment exploiter la dépendance Gotenberg de manière sûre.
• /integrations/gotenberg/boot-and-discovery/ — câblage automatique par le framework.