NextPDF Gotenberg : démarrage rapide

En un coup d’œil

Ce guide convertit un fichier .docx en PDF. À la fin, tu disposes de trois éléments : une passerelle fonctionnelle, une connexion au service vérifiée et un PDF sur disque. Le programme complet se trouve dans le dépôt, à l’emplacement examples/convert-office-to-pdf.php. Les extraits ci-dessous en sont tirés.

Cette page est un tutoriel ; elle présente donc d’abord le parcours nominal. Les enjeux de production — provenance des secrets, tentatives répétées, délais d’expiration et observabilité — sont traités dans /integrations/gotenberg/production-usage/.

Avant de commencer

Vérifie ces trois points :

1. composer require nextpdf/gotenberg a été exécuté, et un client PSR-18 ainsi que des fabriques PSR-17 sont installés. Voir /integrations/gotenberg/install/.
2. Un service Gotenberg est accessible en HTTPS. Le simple http:// est rejeté par la passerelle avant qu’aucune requête ne quitte le processus.
3. Tu disposes d’un fichier d’exemple dans l’un de ces formats : .docx, .xlsx, .pptx, .odt, .ods ou .odp. Les autres extensions sont rejetées avec une ValueError.

Étape 1 — décrire le service

GotenbergConfig est un objet-valeur immuable. Il a au minimum besoin de l’URL de base HTTPS de ton service Gotenberg :

use NextPDF\Gotenberg\GotenbergConfig;

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

timeout est le délai d’expiration du transfert en secondes, appliqué par le transport cURL épinglé. apiKey, lorsqu’elle n’est pas vide, est envoyée sous la forme Authorization: Bearer <token>. Laisse apiKey vide si ton déploiement Gotenberg n’exige aucun jeton.

Étape 2 — câbler la passerelle

La passerelle reçoit la configuration ainsi que ses collaborateurs PSR. Injecte également une responseFactory pour activer le transport cURL avec épinglage DNS et TLS :

use NextPDF\Gotenberg\GotenbergBridge;

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

La passerelle ne crée jamais elle-même de client HTTP. Utilise le client PSR-18 et les fabriques PSR-17 que tu as installés. Le fichier d’exemple montre le câblage Guzzle dans un commentaire.

Étape 3 — vérifier la disponibilité

Sonde le service avant de convertir quoi que ce soit. La sonde valide l’URL sans émettre de trafic réseau, puis envoie un HEAD à <apiUrl>/health :

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

isAvailable() renvoie false (sans jamais lever d’exception) pour une URL vide, non HTTPS ou pointant vers une adresse privée, ainsi que pour toute erreur réseau. Un code d’état inférieur à 500 renvoyé par /health signifie que le service est disponible.

Étape 4 — convertir

convertFile() prend un chemin sur disque. Le chemin est canonicalisé afin de bloquer la traversée de répertoires. L’extension est associée à un format pris en charge. La taille et le nom de fichier sont contrôlés. Une requête multipart est ensuite envoyée à <apiUrl>/forms/libreoffice/convert :

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

Pour convertir des octets que tu as déjà en mémoire, utilise convertString(). Transmets le nom de fichier d’origine pour que la passerelle puisse détecter l’extension :

$pdf = $bridge->convertString($docxBytes, 'report.docx');

Étape 5 — utiliser le résultat

Le résultat contient trois éléments : les octets du PDF, le format source et un indicateur de validité :

if (! $result->isValid()) {
    throw new \RuntimeException('Result is not a valid PDF.');
}

\file_put_contents('/path/to/report.pdf', $result->pdfData);

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

isValid() vaut vrai lorsque le corps n’est pas vide et commence par %PDF. size() correspond à la longueur en octets. À ce stade, le PDF est un flux ordinaire que tu peux confier à NextPDF pour un post-traitement.

Le programme complet

Le programme complet et exécutable se trouve à examples/convert-office-to-pdf.php dans le dépôt du paquet. Il couvre l’analyse des arguments, la configuration pilotée par l’environnement, la sonde de santé, la gestion exhaustive des erreurs et l’écriture du fichier. Exécute-le ainsi :

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

Et ensuite

• /integrations/gotenberg/configuration/ — chaque option et les règles de sélection du transport.
• /integrations/gotenberg/production-usage/ — secrets, tentatives répétées, délais d’expiration, journalisation, concurrence.
• /integrations/gotenberg/troubleshooting/ — chaque exception que ce code peut lever et ce qu’elle signifie.
• /integrations/gotenberg/integration/ — piloter un pipeline de rendu NextPDF à travers le service.