NextPDF Gotenberg: guida rapida

In sintesi

Questa guida pratica mostra come convertire in PDF un file .docx. Al termine si ottengono tre elementi: un’istanza del bridge funzionante, una connessione al servizio verificata e un PDF su disco. Il programma completo è disponibile nel repository in examples/convert-office-to-pdf.php. Gli snippet riportati di seguito provengono da quel programma.

Questa pagina è un tutorial e mostra quindi anzitutto il percorso ideale. Gli aspetti di produzione — provisioning dei segreti, ritentativi, timeout e osservabilità — sono documentati in /integrations/gotenberg/production-usage/.

Prima di iniziare

Verificare questi tre elementi:

1. Di aver eseguito composer require nextpdf/gotenberg e di avere installati un client PSR-18 e le factory PSR-17. Vedere /integrations/gotenberg/install/.
2. Che un servizio Gotenberg sia raggiungibile tramite HTTPS. Il semplice uso di http:// viene rifiutato dal bridge prima che qualsiasi richiesta lasci il processo.
3. Di disporre di un file di esempio in uno di questi formati: .docx, .xlsx, .pptx, .odt, .ods o .odp. Qualsiasi altra estensione viene rifiutata con un ValueError.

Passo 1 — descrivere il servizio

GotenbergConfig è un value object immutabile. Richiede almeno l’URL di base HTTPS del servizio Gotenberg:

use NextPDF\Gotenberg\GotenbergConfig;

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

timeout indica il timeout di trasferimento in secondi, applicato dal trasporto cURL vincolato. apiKey, se non è vuoto, viene inviato come Authorization: Bearer <token>. Lasciare apiKey vuoto se la distribuzione Gotenberg non richiede un token.

Passo 2 — collegare il bridge

Il bridge accetta la configurazione e i relativi collaboratori PSR. Iniettare anche un responseFactory per abilitare il trasporto cURL con vincoli DNS e TLS:

use NextPDF\Gotenberg\GotenbergBridge;

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

Il bridge non crea mai autonomamente un client HTTP. Usare il client PSR-18 e le factory PSR-17 già installati. Il file di esempio mostra in un commento come collegare Guzzle.

Passo 3 — verificare la disponibilità

Verificare la disponibilità del servizio prima di convertire qualsiasi cosa. Il controllo convalida l’URL senza generare traffico di rete, quindi invia un HEAD a <apiUrl>/health:

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

isAvailable() restituisce false (non solleva mai eccezioni) in caso di URL vuoto, non HTTPS o che punta a un indirizzo privato, oltre che per qualsiasi errore di rete. Uno status code inferiore a 500 restituito da /health significa che il servizio è disponibile.

Passo 4 — convertire

convertFile() accetta un percorso su disco. Il percorso viene canonicalizzato per bloccare il path traversal. L’estensione viene mappata su un formato supportato. Vengono controllati anche dimensione e nome del file. Una richiesta multipart viene quindi inviata a <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;
}

Per convertire byte già in memoria, usare convertString(). Passare il nome del file originale affinché il bridge possa rilevare l’estensione:

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

Passo 5 — usare il risultato

Il risultato contiene tre elementi: i byte del PDF, il formato di origine e un controllo di 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() risulta true quando il corpo non è vuoto e inizia con %PDF. size() è la lunghezza in byte. A questo punto, il PDF è un normale flusso che può essere passato a NextPDF per la post-elaborazione.

Il programma completo

Il programma completo ed eseguibile è disponibile in examples/convert-office-to-pdf.php nel repository del pacchetto. Copre l’analisi degli argomenti, la configurazione basata sull’ambiente, il controllo di integrità, la gestione esaustiva degli errori e la scrittura dell’output. Eseguirlo con:

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

Cosa fare dopo

• /integrations/gotenberg/configuration/ — tutte le opzioni e le regole di selezione del trasporto.
• /integrations/gotenberg/production-usage/ — segreti, ritentativi, timeout, logging, concorrenza.
• /integrations/gotenberg/troubleshooting/ — tutte le eccezioni che questo codice può sollevare e il loro significato.
• /integrations/gotenberg/integration/ — guidare una pipeline di rendering NextPDF attraverso il servizio.