Référence de l'API Gotenberg

En bref

Le package Gotenberg expose un seul pont de service, GotenbergBridge, qui convertit un document bureautique (docx, xlsx, pptx, odt, ods, odp) en PDF en l’envoyant par POST à un service Gotenberg externe. Autour de ce pont se trouvent les value objects de support que tu lis ou que tu fournis : GotenbergConfig (le descripteur de service immuable et ses limites), OfficeFormat (l’enum des formats pris en charge), GotenbergConvertPayload (le corps de la requête multipart) et GotenbergConvertResult (la réponse PDF analysée). Un second niveau — GotenbergSecurityPolicy, GotenbergResponseParser et PinnedCurlTransport — regroupe la validation, l’analyse et le transport épinglé que le pont pilote en interne. Tu n’y touches que pour écrire du code de transport personnalisé ou du code de test.

Commence ici : construis un GotenbergConfig avec l’URL HTTPS de ton service, puis raccorde-le à un GotenbergBridge avec ton client PSR-18 et tes factories PSR-17. Appelle ensuite convertFile() ou convertString(), puis lis pdfData dans le GotenbergConvertResult retourné.

Tâches courantes

Voici les opérations que tu effectues le plus souvent avec ce package, chacune accompagnée d’un extrait vérifié et exécutable.

Convertir un fichier sur disque en PDF

Indique un chemin au pont ; le format est détecté à partir de l’extension.

<?php

declare(strict_types=1);

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: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    responseFactory: $psrResponseFactory,
);

$result = $bridge->convertFile('/path/to/report.docx');

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

Ce que cela fait : valide l’URL, le chemin, la taille et le nom de fichier, envoie une seule requête multipart, puis écrit les octets PDF retournés sur disque.

Convertir des octets en mémoire en PDF

Utilise convertString() quand tu as déjà les octets ; le nom de fichier sert à détecter le format.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

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

Ce que cela fait : détecte xlsx à partir du nom de fichier, convertit les octets et confirme que le résultat commence bien par la signature %PDF avant que tu ne l’utilises.

Sonder la disponibilité du service avant de convertir

Fais dépendre le traitement de isAvailable(), qui valide l’URL sans aucun trafic, puis envoie une seule requête HEAD vers /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Ce que cela fait : retourne 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, ce qui te permet d’arrêter le traitement en amont avant de lancer une conversion.

Pont

Ce tableau décrit l’interface du pont — utilise-le quand tu construis GotenbergBridge ou que tu appelles ses méthodes de conversion et de disponibilité.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Config, client PSR-18, factories PSR-17, logger optionnel, politique HTML optionnelle, factory de réponse optionnelle.	Utilise `DefaultHtmlSecurityPolicy` quand aucune politique n’est fournie.	`GotenbergBridge`	Erreurs de câblage du conteneur.	La factory de réponse active le transport cURL épinglé quand l’épinglage est nécessaire.
`GotenbergBridge::convertFile(string $filePath)`	Chemin du système de fichiers vers un document bureautique.	Utilise l’extension de fichier pour détecter le format.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` pour un format non pris en charge.	Résout le chemin réel, puis vérifie la lisibilité, la taille et le nom de fichier.
`GotenbergBridge::convertString(string $content, string $fileName)`	Octets bruts et nom de fichier d’origine.	Utilise l’extension du nom de fichier pour détecter le format.	`GotenbergConvertResult`	Identique à `convertFile`.	À utiliser quand l’application a déjà les octets du fichier.
`GotenbergBridge::isAvailable()`	aucun.	Requête HEAD vers `/health` quand la config est valide.	`bool`	Retourne `false` en cas d’erreur.	Signal de disponibilité uniquement.
`GotenbergBridge::getHtmlSecurityPolicy()`	aucun.	Retourne la politique configurée pour la couche d’analyse.	`HtmlSecurityPolicyInterface`	aucune attendue.	Complète la politique de sécurité au niveau du transport.

Configuration et payloads

Ce tableau couvre les value objects que tu construis à la main — le descripteur de service GotenbergConfig et les objets de requête et de réponse GotenbergConvertPayload/GotenbergConvertResult — quand tu as besoin d’un contrôle plus fin que celui offert par les deux points d’entrée de conversion.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	URL de l’API, timeout, taille de fichier maximale, jeton bearer, jeux d’épingles.	Une URL vide est invalide ; la taille maximale par défaut est de 50 Mio.	`GotenbergConfig`	aucune attendue.	Garde la clé d’API secrète.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, tableaux d’épingles.	Les valeurs optionnelles manquantes utilisent les valeurs par défaut du constructeur.	`GotenbergConfig`	aucune attendue.	Les listes de chaînes ignorent les valeurs qui ne sont pas des chaînes.
`GotenbergConfig::isValid()`	aucun.	Valide quand l’URL de l’API est non vide.	`bool`	aucune attendue.	La sûreté de l’URL est validée avant toute E/S réseau.
`GotenbergConfig::allPublicKeyPins()`	aucun.	Combine les épingles primaires et de secours.	`list<string>`	aucune attendue.	Une liste vide désactive l’épinglage.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Nom de fichier, octets, format, indicateur d’orientation, plages de pages.	Portrait ; toutes les pages.	`GotenbergConvertPayload`	aucune attendue.	Le payload est converti en données de formulaire multipart.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Délimiteur multipart.	Inclut le champ de plage de pages uniquement quand il est non vide.	`string`	aucune attendue.	Le délimiteur est généré par le pont.
`GotenbergConvertPayload::contentType(string $boundary)`	Délimiteur multipart.	Utilise `multipart/form-data`.	`string`	aucune attendue.	À attacher comme `Content-Type` de la requête.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Octets du PDF converti, format source, durée de rendu optionnelle.	La durée de rendu vaut `0.0` quand elle n’est pas mesurée.	`GotenbergConvertResult`	aucune attendue.	Retourné par `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	aucun.	Valide quand les octets du PDF converti sont non vides et ressemblent à des données PDF.	`bool`	aucune attendue.	À vérifier avant de persister ou de streamer le résultat.
`GotenbergConvertResult::size()`	aucun.	Compte les octets du PDF converti.	`int`	aucune attendue.	À utiliser pour les quotas, la télémétrie et les limites de réponse.

Formats bureautiques

Ce tableau concerne l’enum OfficeFormat. Utilise-le quand tu as besoin de mapper une extension vers un format, de lire son type MIME d’upload ou de vérifier lesquels des six formats sont pris en charge.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`OfficeFormat::fromExtension(string $ext)`	Extension de fichier avec ou sans point initial.	Correspondance insensible à la casse.	`OfficeFormat`	`ValueError` pour une extension non prise en charge.	Valeurs prises en charge : `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	aucun.	Mappe le cas de l’enum vers le type MIME d’upload.	`string`	aucune attendue.	Utilisé dans la partie fichier multipart.
`OfficeFormat::extension()`	aucun.	Retourne la valeur sous-jacente.	`string`	aucune attendue.	Utile pour les diagnostics et les noms de fichiers.

Sécurité, analyse et transport

Ce tableau décrit la couche interne que le pont pilote pour toi. Utilise-le uniquement pour écrire un transport personnalisé, un appel HTTP sur mesure qui a quand même besoin de l’analyse du package, ou des diagnostics de bas niveau sur la sécurité et l’épinglage.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	URL de base de l’API.	Analyse et valide la destination avant toute E/S réseau.	`array`	`RuntimeException` pour les URL dangereuses ou invalides.	Empêche les endpoints à risque SSRF d’atteindre le code de conversion.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Hôte et liste d’IP épinglées.	Vérifie que les attentes d’épinglage DNS restent satisfaites.	`void`	`RuntimeException` quand les épingles sont périmées ou invalides.	À utiliser dans les déploiements épinglés et les diagnostics opérationnels.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Taille réelle et maximum configuré.	Accepte les fichiers égaux ou inférieurs à la limite configurée.	`void`	`RuntimeException` quand le fichier est trop volumineux.	À appliquer avant la construction de la requête.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Nom de fichier d’origine.	Rejette les noms de fichier dangereux ou non pris en charge.	`void`	`RuntimeException` pour les noms invalides.	Empêche la création de parties multipart avec un nom de fichier malformé.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	Réponse PSR-7 et format bureautique attendu.	Extrait les octets du PDF converti d’une réponse réussie.	`GotenbergConvertResult`	`GotenbergConvertException` pour les réponses en échec ou une sortie PDF invalide.	Analyseur central pour la conversion depuis un fichier ou une chaîne.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	Factories PSR-17, IP épinglées, clés publiques épinglées, timeout.	Aucune épingle et timeout de 30 secondes.	`PinnedCurlTransport`	aucune attendue.	À utiliser uniquement quand l’épinglage au niveau cURL est requis.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	Requête PSR-7.	Envoie la requête via cURL avec le timeout configuré et les contrôles d’épinglage.	`ResponseInterface`	`GotenbergConvertException` en cas d’échec cURL/transport.	À utiliser quand l’épinglage ne peut pas être délégué à un autre client HTTP.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Requête, hôte et port.	Construit le tableau d’options cURL utilisé par `sendRequest()`.	`array`	Erreurs liées à une requête invalide ou à une configuration d’épingle.	Diagnostics de bas niveau et point d’accroche de test.

Notes de développement

Traite Gotenberg comme une frontière de service externe. Configure explicitement le timeout, la taille, l’URL et la politique d’épinglage.
convertFile() lit l’intégralité du fichier en mémoire avant la construction de la requête.
Journalise des métadonnées, comme le nom de fichier et la longueur du contenu, pas le contenu du fichier.