Riferimento API Gotenberg

In breve

Il pacchetto Gotenberg espone un bridge di servizio, GotenbergBridge, che converte in PDF un documento Office (docx, xlsx, pptx, odt, ods, odp) inviandolo tramite POST a un servizio Gotenberg esterno. Attorno a questo bridge si trovano i value object di supporto da leggere o fornire: GotenbergConfig (il descrittore di servizio immutabile e i relativi limiti), OfficeFormat (l’enum dei formati supportati), GotenbergConvertPayload (il corpo della richiesta multipart) e GotenbergConvertResult (la risposta PDF già analizzata). Un secondo livello — GotenbergSecurityPolicy, GotenbergResponseParser e PinnedCurlTransport — fornisce il meccanismo di convalida, parsing e trasporto con pinning che il bridge utilizza internamente. Da usare solo quando si scrive codice di trasporto personalizzato o di test.

Punto di partenza: costruire un GotenbergConfig con l’URL HTTPS del servizio e passarlo a un GotenbergBridge insieme al client PSR-18 e alle factory PSR-17. Quindi chiamare convertFile() o convertString() e leggere pdfData dal GotenbergConvertResult restituito.

Attività comuni

Queste sono le attività più frequenti in scenari reali con questo pacchetto, ciascuna accompagnata da uno snippet eseguibile e verificato.

Convertire in PDF un file su disco

Passare al bridge un percorso; il formato viene rilevato dall’estensione.

<?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);

Cosa fa: convalida l’URL, il percorso, la dimensione e il nome del file, invia una singola richiesta multipart e scrive su disco i byte del PDF restituito.

Convertire in PDF byte già in memoria

Usare convertString() quando si dispone già dei byte; il nome del file determina il formato rilevato.

<?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.');
}

Cosa fa: rileva xlsx dal nome del file, converte i byte e verifica che il risultato inizi con la firma %PDF prima dell’uso.

Verificare la disponibilità del servizio prima di convertire

Subordinare l’operazione a isAvailable(), che convalida l’URL senza generare traffico e poi invia una sola HEAD a /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Cosa fa: restituisce false (senza mai sollevare eccezioni) per un URL vuoto, non HTTPS o con indirizzo privato, e per qualsiasi errore di rete, così da poter interrompere rapidamente il flusso prima di avviare una conversione.

Bridge

Questa tabella descrive la superficie del bridge: usarla quando si costruisce GotenbergBridge o si chiamano i suoi metodi di conversione e disponibilità.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Config, client PSR-18, factory PSR-17, logger opzionale, policy HTML opzionale, response factory opzionale.	Usa `DefaultHtmlSecurityPolicy` quando non viene fornita alcuna policy.	`GotenbergBridge`	Errori di wiring del container.	La response factory abilita il trasporto cURL con pinning quando il pinning è necessario.
`GotenbergBridge::convertFile(string $filePath)`	Percorso del filesystem verso un documento office.	Usa l’estensione del file per rilevare il formato.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` per formato non supportato.	Risolve il percorso reale e verifica leggibilità, dimensione e nome del file.
`GotenbergBridge::convertString(string $content, string $fileName)`	Byte non elaborati e nome del file originale.	Usa l’estensione del nome del file per rilevare il formato.	`GotenbergConvertResult`	Come `convertFile`.	Da usare quando l’applicazione dispone già dei byte del file.
`GotenbergBridge::isAvailable()`	nessuno.	Richiesta HEAD a `/health` quando la configurazione è valida.	`bool`	Restituisce `false` in caso di errori.	Semplice segnale di disponibilità.
`GotenbergBridge::getHtmlSecurityPolicy()`	nessuno.	Restituisce la policy configurata per il livello di parsing.	`HtmlSecurityPolicyInterface`	nessuno previsto.	Integra la policy di sicurezza a livello di trasporto.

Configurazione e payload

Questa tabella copre i value object da costruire manualmente — il descrittore di servizio GotenbergConfig e i carrier di richiesta e risposta GotenbergConvertPayload/GotenbergConvertResult — quando serve un controllo più fine rispetto ai due entry point di conversione.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	URL dell’API, timeout, dimensione massima del file, token bearer, set di pin.	Un URL vuoto non è valido; la dimensione massima predefinita è 50 MiB.	`GotenbergConfig`	nessuno previsto.	Mantenere riservata la chiave API.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, array di pin.	I valori opzionali mancanti usano i valori predefiniti del costruttore.	`GotenbergConfig`	nessuno previsto.	Gli elenchi di stringhe ignorano i valori non stringa.
`GotenbergConfig::isValid()`	nessuno.	Valido quando l’URL dell’API non è vuoto.	`bool`	nessuno previsto.	La sicurezza dell’URL viene convalidata prima dell’I/O di rete.
`GotenbergConfig::allPublicKeyPins()`	nessuno.	Combina i pin primari e di backup.	`list<string>`	nessuno previsto.	Un elenco vuoto disabilita il pinning.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Nome del file, byte, formato, flag di orientamento, intervalli di pagine.	Verticale; tutte le pagine.	`GotenbergConvertPayload`	nessuno previsto.	Il payload viene convertito in dati di form multipart.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Boundary multipart.	Include il campo dell’intervallo di pagine solo quando non è vuoto.	`string`	nessuno previsto.	Il boundary è generato dal bridge.
`GotenbergConvertPayload::contentType(string $boundary)`	Boundary multipart.	Usa `multipart/form-data`.	`string`	nessuno previsto.	Allegare come `Content-Type` della richiesta.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Byte del PDF convertito, formato di origine, durata di rendering opzionale.	La durata di rendering è `0.0` quando non viene misurata.	`GotenbergConvertResult`	nessuno previsto.	Restituito da `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	nessuno.	Valido quando i byte del PDF convertito non sono vuoti e hanno l’aspetto di dati PDF.	`bool`	nessuno previsto.	Da verificare prima di rendere persistente il risultato o trasmetterlo in streaming.
`GotenbergConvertResult::size()`	nessuno.	Conta i byte del PDF convertito.	`int`	nessuno previsto.	Da usare per quote, telemetria e limiti delle risposte.

Formati office

Questa tabella riguarda l’enum OfficeFormat. Da usare quando occorre mappare un’estensione a un formato, leggere il relativo tipo MIME di upload o verificare quali sono i sei formati supportati.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`OfficeFormat::fromExtension(string $ext)`	Estensione del file con o senza punto iniziale.	Confronto senza distinzione tra maiuscole e minuscole.	`OfficeFormat`	`ValueError` per estensione non supportata.	Valori supportati: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	nessuno.	Mappa il case dell’enum sul tipo MIME di upload.	`string`	nessuno previsto.	Usato nella parte file del multipart.
`OfficeFormat::extension()`	nessuno.	Restituisce il valore di backing.	`string`	nessuno previsto.	Utile per diagnostica e nomi di file.

Sicurezza, parsing e trasporto

Questa tabella descrive il meccanismo interno che il bridge usa per conto dell’utente. Da usare solo quando si scrive un trasporto personalizzato, una chiamata HTTP su misura che richiede comunque il parsing del pacchetto oppure per la diagnostica di basso livello su sicurezza e pinning.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	URL di base dell’API.	Analizza e convalida la destinazione prima dell’I/O di rete.	`array`	`RuntimeException` per URL non sicuri o non validi.	Mantiene gli errori di endpoint di tipo SSRF fuori dal codice di conversione.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Host ed elenco di IP con pinning.	Verifica le aspettative di pinning DNS.	`void`	`RuntimeException` quando i pin sono obsoleti o non validi.	Da usare nei deployment con pinning e nella diagnostica operativa.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Dimensione effettiva e massimo configurato.	Accetta i file pari o inferiori al limite configurato.	`void`	`RuntimeException` quando il file è troppo grande.	Da applicare prima della costruzione della richiesta.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Nome del file originale.	Rifiuta forme del nome del file non sicure o non supportate.	`void`	`RuntimeException` per nomi non validi.	Previene nomi di file multipart non corretti.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	Risposta PSR-7 e formato office atteso.	Estrae i byte del PDF convertito da una risposta riuscita.	`GotenbergConvertResult`	`GotenbergConvertException` per risposte non riuscite o output PDF non valido.	Parser centrale sia per la conversione da file sia per quella da stringa.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	Factory PSR-17, IP con pinning, chiavi pubbliche con pinning, timeout.	Nessun pin e timeout di 30 secondi.	`PinnedCurlTransport`	nessuno previsto.	Da usare solo quando è richiesto il pinning a livello di cURL.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	Richiesta PSR-7.	Invia tramite cURL con il timeout e i controlli di pinning configurati.	`ResponseInterface`	`GotenbergConvertException` in caso di errore di cURL/trasporto.	Da usare quando il pinning non può essere delegato a un altro client HTTP.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Richiesta, host e porta.	Costruisce l’array di opzioni cURL usato da `sendRequest()`.	`array`	Errori di richiesta non valida o di configurazione dei pin.	Diagnostica di basso livello e hook di test.

Note di sviluppo

Trattare Gotenberg come un confine di servizio esterno. Configurare in modo esplicito timeout, dimensione, URL e policy di pinning.
convertFile() legge l’intero file in memoria prima di costruire la richiesta.
Registrare metadati come nome del file e lunghezza del contenuto, non il contenuto del file.