Integrazione di NextPDF con Gotenberg

In sintesi

Questa pagina mostra come collegare il bridge al resto di un’applicazione: installarlo, collegarlo e poi integrare il PDF convertito in un flusso di post-elaborazione NextPDF. Il bridge trasforma un documento Office in PDF; il flusso gestisce tutto ciò che viene dopo. È il complemento operativo di /integrations/gotenberg/boot-and-discovery/, che spiega perché il collegamento è strutturato in questo modo.

Installazione

composer require nextpdf/gotenberg

Questo include nextpdf/core ^3.0 e i contratti HTTP PSR. Installare separatamente un client PSR-18 e le factory PSR-17 come pacchetti distinti. Il bridge dipende solo dalle interfacce, quindi la scelta delle librerie concrete resta libera. Per l’installazione completa, compresa la predisposizione del servizio Gotenberg su HTTPS, vedere /integrations/gotenberg/install/.

Collegamento

Creare il bridge con un oggetto di configurazione e i collaboratori PSR. Iniettare anche una factory di risposta, che abilita il trasporto con DNS-pinning e TLS-pinning:

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: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

Il bridge richiede HTTPS per l’URL configurato. Rifiuta un semplice http:// prima di effettuare qualsiasi richiesta. Eseguire Gotenberg dietro una terminazione TLS e puntare il bridge all’endpoint HTTPS.

Binding del container

Registrare tre elementi nel container dell’host. Il primo è GotenbergConfig, costruito dalla propria sorgente di configurazione. Il secondo è il client PSR-18 con le factory PSR-17. Il terzo è GotenbergBridge, collegato a partire dai primi due. Questo pacchetto non fornisce binding propri. La registrazione nativa del framework spetta ai pacchetti di integrazione dedicati al rispettivo framework. Vedere /integrations/gotenberg/boot-and-discovery/.

Configurazione

Il descrittore del servizio e i relativi limiti sono tutti campi di GotenbergConfig. Comprendono l’URL dell’API, il timeout, il limite di dimensione, il bearer token e i pin TLS. Le opzioni per singola richiesta, landscape e nativePageRanges, sono invece campi del tipo di payload. /integrations/gotenberg/configuration/ documenta ogni campo, con tipo, valore predefinito ed effetto.

Integrare il PDF convertito in un flusso NextPDF

Un tipico flusso end-to-end:

1. Convertire il documento Office con convertFile() o convertString().
2. Prelevare $result->pdfData, che contiene i byte grezzi del PDF, e caricarlo in un documento NextPDF.
3. Applicare la post-elaborazione, ad esempio assemblaggio delle pagine, applicazione di filigrane, conversione PDF/A o firme digitali.

Il passaggio 3 è responsabilità di NextPDF, non del bridge. Il pacchetto nextpdf/premium fornisce firme, profili PDF/A e applicazione di filigrane. Mantenere conversione e post-elaborazione come fasi separate. In questo modo è possibile diagnosticare ogni errore separatamente.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

Il supporto PAdES dell’edizione Pro riguarda solo il livello base B-B. Non fornisce B-T, B-LT o B-LTA. La conversione di un documento tramite questo bridge non implica alcuna capacità di marcatura temporale o di validazione a lungo termine.

Smoke test

Una volta collegato il bridge, verificare l’integrazione. È possibile farlo senza convertire un documento reale:

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

isAvailable() convalida l’URL senza generare traffico di rete. Invia quindi una HEAD a <apiUrl>/health. Poi convertire un piccolo documento valido e affidabile. In questo modo viene esercitato l’intero percorso multipart verso <apiUrl>/forms/libreoffice/convert, insieme alla convalida della risposta.

Punti di ingresso dell’API pubblica

La superficie pubblica utilizzata da questa integrazione comprende:

• GotenbergConfig — descrittore del servizio e limiti immutabili; fromArray() lo costruisce da un array di configurazione.
• GotenbergBridge::convertFile(string $path) — converte un file su disco.
• GotenbergBridge::convertString(string $bytes, string $fileName) — converte byte presenti in memoria.
• GotenbergBridge::isAvailable() — controllo di prontezza che non solleva eccezioni.
• GotenbergConvertResult — contiene pdfData, sourceFormat, isValid() e size().
• GotenbergConvertException — il tipo di eccezione del livello di conversione.

Il contratto completo è in /integrations/gotenberg/configuration/ e /integrations/gotenberg/troubleshooting/. Copre la selezione del trasporto e il catalogo delle eccezioni.

Vedere anche

• /integrations/gotenberg/boot-and-discovery/ — perché il collegamento è strutturato in questo modo.
• /integrations/gotenberg/quickstart/ — una prima conversione guidata.
• /integrations/gotenberg/production-usage/ — segreti, tentativi ripetuti, timeout e osservabilità.
• /integrations/gotenberg/install/ — installazione del pacchetto e del servizio Gotenberg.