Installazione di NextPDF Gotenberg

In sintesi

L’installazione del bridge si compone di due parti. La prima riguarda il pacchetto PHP e le relative dipendenze PSR HTTP, da installare con Composer. La seconda riguarda il servizio Gotenberg richiamato dal pacchetto. Il bridge delega la conversione a tale servizio; di conseguenza, non può convertire nulla finché un’istanza Gotenberg non risulta raggiungibile.

Completare entrambe le parti prima di scrivere codice di conversione.

Requisiti

Requisito	Vincolo	Motivo
PHP	>=8.4 <9.0	Il pacchetto dichiara questo intervallo in composer.json.
core di NextPDF	^3.0	Dipendenza diretta dichiarata in composer.json.
Client HTTP PSR-18	^1.0	Il bridge invia le richieste tramite un Psr\Http\Client\ClientInterface iniettato.
Factory HTTP PSR-17	^1.1	Il bridge costruisce richieste e flussi tramite factory PSR-17 iniettate.
Logger PSR-3	^3.0 (facoltativo)	È possibile iniettare un logger per registrare il debug a livello di richiesta.
Servizio Gotenberg	Raggiungibile via HTTPS	La conversione viene eseguita dal servizio esterno, non da questo pacchetto.

Il bridge non include un client PSR-18 né factory PSR-17. Le implementazioni devono quindi essere scelte separatamente. Ad esempio, è possibile abbinare un client basato su Guzzle alle relative factory PSR-17, oppure il client HTTP di Symfony a nyholm/psr7. Qualsiasi implementazione conforme ai contratti PSR pertinenti funziona, perché il bridge dipende solo dalle interfacce e non da una libreria specifica.

Passo 1 — installare il pacchetto

Aggiungere il pacchetto con Composer:

composer require nextpdf/gotenberg

In questo modo vengono risolti nextpdf/core ^3.0 e i contratti PSR HTTP: psr/http-client, psr/http-factory e psr/log. Non installa un client HTTP concreto.

Passo 2 — installare un client PSR-18 e factory PSR-17

Installare un client PSR-18 e il relativo insieme di factory PSR-17. Con Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Oppure con il client HTTP di Symfony e Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

Il bridge riceve questi elementi come argomenti del costruttore. Non costruisce mai autonomamente un client HTTP. La scelta spetta quindi interamente all’utente e va effettuata durante il cablaggio del bridge. Vedere /integrations/gotenberg/configuration/ per la forma del costruttore e /integrations/gotenberg/quickstart/ per un esempio completo di cablaggio.

Passo 3 — predisporre un servizio Gotenberg

Il bridge richiama la route di conversione LibreOffice di Gotenberg; serve quindi un’istanza Gotenberg che il bridge possa raggiungere. Il progetto upstream pubblica un’immagine container. Il comando canonico per lo sviluppo locale è:

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

Questo espone Gotenberg sulla porta 3000 tramite HTTP non cifrato, configurazione adatta solo allo sviluppo locale. Il bridge richiede HTTPS per l’URL dell’API configurato. Rifiuta http:// non cifrato prima dell’invio di qualsiasi richiesta. Per qualsiasi scenario che vada oltre un esperimento locale, collocare Gotenberg dietro un reverse proxy con terminazione TLS o un service mesh, quindi puntare il bridge all’endpoint HTTPS. /integrations/gotenberg/security-and-operations/ illustra la forma del deployment di produzione, l’esposizione di rete e l’autenticazione.

Il tag dell’immagine mostrato qui (gotenberg/gotenberg:8) è la linea principale upstream di Gotenberg. Il README di questo progetto e la baseline di integrazione fanno riferimento a tale linea. In produzione, fissare un tag di patch specifico anziché seguire un tag principale mobile. Verificare inoltre i percorsi delle route (/forms/libreoffice/convert, /health) rispetto alla versione di Gotenberg che si distribuisce. Il bridge presuppone questi due percorsi e non formula altre assunzioni sul servizio.

Passo 4 — verificare il cablaggio

A questo punto il pacchetto e un client HTTP risultano installati e Gotenberg è raggiungibile via HTTPS. Prima di tentare una conversione reale, confermare che il servizio sia visibile al bridge tramite la sonda di stato integrata:

<?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() convalida prima l’URL configurato. Restituisce false per un URL vuoto, non HTTPS o con indirizzo privato senza generare traffico di rete. Invia quindi una richiesta HEAD a <apiUrl>/health e segnala il servizio come disponibile quando lo stato è inferiore a 500. Un errore di rete viene intercettato e segnalato come non disponibile, anziché essere sollevato.

Nota sulla versione

Questa documentazione descrive il pacchetto per la linea ^3.0. Tale linea corrisponde al requisito in composer.json e alla matrice di supporto in SECURITY.md, dove la 3.x risulta supportata e la 2.x no. I precedenti riferimenti a 0.x nelle pagine scheletro presenti nel repository precedono la linea 3.0; il vincolo in composer.json li sostituisce.

Vedere anche

• /integrations/gotenberg/overview/ — funzione del bridge e formati convertiti.
• /integrations/gotenberg/configuration/ — ogni argomento del costruttore e campo di configurazione.
• /integrations/gotenberg/quickstart/ — una prima conversione completa ed eseguibile.
• /integrations/gotenberg/security-and-operations/ — come gestire la dipendenza Gotenberg in modo sicuro.
• /integrations/gotenberg/boot-and-discovery/ — cablaggio automatico del framework.