Guida per sviluppatori Gotenberg

In breve

Il pacchetto Gotenberg delega la conversione a un servizio esterno. Il codice applicativo deve esplicitare il confine del servizio: convalidare l’input, costruire un payload, inviare la richiesta, analizzare il risultato e gestire i malfunzionamenti del servizio.

Usare questa guida per creare workflow di conversione da Office a PDF, endpoint di caricamento, controlli di integrità del servizio o criteri di trasporto basati su nextpdf/gotenberg.

Confine architetturale

Livello	Di proprietà di	Responsabilità	Da non inserire qui
Caricamento o origine del documento	Applicazione	Autorizzare il chiamante, convalidare l’origine, scegliere i criteri di conversione.	Decisioni sull’URL del servizio o sul pinning del trasporto.
Rilevamento del formato	`nextpdf/gotenberg`	Mappare le estensioni sicure su `OfficeFormat`.	Affidarsi al tipo MIME senza convalida applicativa.
Bridge	`nextpdf/gotenberg`	Costruire la richiesta multipart, chiamare Gotenberg, analizzare la risposta PDF.	Query di dominio o criteri di archiviazione.
Servizio Gotenberg	Distribuzione	Convertire il documento Office in PDF.	Autorizzazione dell’applicazione PHP.
Motore principale	`nextpdf/nextpdf`	Importare o combinare, se necessario, i dati PDF convertiti.	Conversione Office.

Ciclo di vita del runtime

Fase	Comportamento	Azione dello sviluppatore
Creazione della configurazione	Vengono caricati l’URL dell’API, il timeout, la dimensione massima, la chiave API e i pin.	Tenere l’URL del servizio e il token fuori dal codice sorgente.
Convalida dell’input	Vengono verificati il percorso del file, la dimensione del file, il nome del file, l’estensione e la sicurezza dell’URL.	Rifiutare l’input non supportato prima dell’invio.
Costruzione del payload	`GotenbergConvertPayload` costruisce i dati del modulo multipart.	Conservare il nome del file originale solo quando è sicuro.
Richiesta al servizio	Il bridge invia la richiesta a `/forms/libreoffice/convert`.	Configurare il timeout e i criteri di trasporto.
Analisi del risultato	`GotenbergResponseParser::parse()` restituisce i byte del PDF e i metadati.	Trattare le risposte non PDF o di errore come errori di conversione.

Struttura dell’applicazione consigliata

Percorso	Scopo
`app/Pdf/Conversion/*`	Wrapper applicativo attorno a `GotenbergBridge`.
`app/Pdf/Uploads/*`	Convalida del caricamento, archiviazione e criteri per i nomi dei file.
`app/Pdf/ConversionPolicy/*`	Criteri di selezione per dimensione, formato e servizio.
`tests/Pdf/Conversion/*`	Test su formato, file, servizio e trasporto.

Mantenere separata la convalida dei file dalla conversione. Un servizio di conversione deve ricevere input già autorizzato, continuando comunque ad affidarsi alla convalida del pacchetto come difesa in profondità.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

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

        return $result->pdfData;
    }
}

Pattern di conversione

Pattern	API	Quando usarlo	Vincolo
Convertire da un percorso file	`GotenbergBridge::convertFile()`	Il documento è già archiviato su disco.	Il percorso deve essere leggibile e approvato dai criteri.
Convertire i byte in memoria	`GotenbergBridge::convertString()`	L’applicazione dispone già dei byte provenienti da un caricamento o da un object store.	Il nome del file continua comunque a determinare il rilevamento del formato.
Costruire il payload direttamente	`GotenbergConvertPayload`	I test o il codice di trasporto personalizzato richiedono i byte multipart.	Mantenere la generazione del boundary al di fuori dell’input utente.
Analizzare la risposta direttamente	`GotenbergResponseParser::parse()`	Una chiamata HTTP personalizzata richiede comunque l’analisi del pacchetto.	È necessario passare l’`OfficeFormat` previsto.

Integrità e prontezza

GotenbergBridge::isAvailable() è un segnale di prontezza. Non deve essere l’unica protezione a runtime. Un servizio può risultare disponibile durante la verifica di prontezza e fallire comunque nella conversione successiva.

Controllo	Scopo	Nota operativa
Validità della configurazione	Rilevare l’URL dell’API mancante.	Eseguire durante l’avvio dell’applicazione o i controlli di distribuzione.
Disponibilità di `/health`	Rilevare se il servizio è raggiungibile.	Usare per i dashboard di prontezza.
Conversione di una piccola fixture	Rilevare un’installazione di LibreOffice non funzionante o una regressione del servizio.	Eseguire in smoke test pianificati, non a ogni richiesta.
Monitoraggio del timeout	Rilevare rallentamenti del servizio.	Tracciare per formato e dimensione del file.

Punti di estensione

Punto di estensione	Usarlo per	Vincolo
PSR-18 `ClientInterface`	Comportamento personalizzato del client HTTP.	Deve rispettare la semantica response/exception di PSR-18.
Factory PSR-17	Creazione di richieste e flussi.	Necessarie per costruire il bridge.
`HtmlSecurityPolicyInterface`	Criteri a livello di analisi per gli input HTML.	Integra i criteri di sicurezza di Gotenberg.
`ResponseFactoryInterface`	Costruzione della risposta per il trasporto cURL con pin.	Necessaria solo quando si usa il percorso di trasporto del pacchetto.
`GotenbergSecurityPolicy`	Convalida di URL, dimensione del file, nome del file e pin.	Mantenere l’autorizzazione applicativa al di fuori di questo livello.

Workflow di sviluppo

Iniziare con convertString() nei test in modo che le fixture siano esplicite.
Aggiungere convertFile() solo dopo aver verificato i percorsi del file system.
Mantenere la dimensione massima del file al di sotto dei limiti del servizio e dell’infrastruttura.
Usare isAvailable() per i segnali di prontezza, non come sostituto della gestione degli errori.
Registrare nei log nome del file, formato, dimensione, stato e durata. Non registrare nei log i byte del documento.
Aggiungere test di timeout e degli scenari di errore prima di esporre gli endpoint di caricamento.

Gestione degli errori

Errore	Dove deve essere gestito	Risposta consigliata
Estensione non supportata	Rilevamento del formato.	Rifiutare prima dell’invio al servizio.
Nome file non sicuro	Criteri di sicurezza.	Rifiutare e normalizzare i criteri di denominazione per i caricamenti.
File troppo grande	Criteri di caricamento e convalida del pacchetto.	Rifiutare prima di leggere o inviare payload di grandi dimensioni.
Gotenberg non disponibile	Confine del bridge.	Restituire un errore applicativo ritentabile quando appropriato.
Risposta non PDF	Parser della risposta.	Considerarla un errore di conversione e acquisire lo stato del servizio.
Errore di convalida del pin o dell’URL	Criteri di trasporto.	Applicare il fail-closed e avvisare gli operatori.

Impostazioni predefinite sicure

Aspetto	Valore predefinito	Quando eseguire l’override
Timeout	`30` secondi.	Aumentarlo solo dopo aver misurato la latenza reale del servizio.
Dimensione massima del file	`52,428,800` byte.	Ridurla per gli endpoint pubblici o multi-tenant.
Chiave API	Vuota.	Impostarla per distribuzioni Gotenberg private.
Formati supportati	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	Aggiungere formati solo quando `OfficeFormat` e il parser li supportano.
Set di pin	Vuoto.	Aggiungere i pin solo con pin di backup e una procedura di rotazione.

Checklist di test

I test di formato coprono le estensioni supportate e non supportate.
I test sui file coprono nomi di file mancanti, illeggibili, troppo grandi e non sicuri.
I test del servizio coprono le risposte non 2xx, i corpi di risposta non validi e le eccezioni di trasporto.
I test di sicurezza coprono gli URL del servizio privati o non validi quando sono vietati dai criteri.
I test di timeout verificano che il timeout configurato venga passato al trasporto.
I test delle fixture mantengono i documenti di esempio piccoli e non sensibili.