Gotenberg-Entwicklerhandbuch

Auf einen Blick

Das Gotenberg-Paket delegiert die Konvertierung an einen externen Dienst. Anwendungscode sollte die Dienstgrenze ausdrücklich abbilden: Eingaben validieren, einen Payload aufbauen, die Anfrage senden, das Ergebnis parsen und Dienstfehler behandeln.

Verwenden Sie dieses Handbuch, wenn Sie Workflows für die Office-zu-PDF-Konvertierung, Upload-Endpunkte, Dienst-Health-Checks oder Transport-Policys rund um nextpdf/gotenberg entwickeln.

Architekturgrenze

Schicht	Verantwortlich	Zuständigkeit	Nicht hierher legen
Upload- oder Dokumentquelle	Anwendung	Aufrufer autorisieren, Quelle validieren, Konvertierungs-Policy auswählen.	Entscheidungen zur Dienst-URL oder zum Transport-Pinning.
Formaterkennung	`nextpdf/gotenberg`	Sichere Erweiterungen auf `OfficeFormat` abbilden.	Vertrauen in MIME-Angaben ohne Anwendungsvalidierung.
Brücke	`nextpdf/gotenberg`	Multipart-Anfrage aufbauen, Gotenberg aufrufen, PDF-Antwort parsen.	Domänenabfragen oder Speicher-Policy.
Gotenberg-Dienst	Deployment	Office-Dokumente in PDF konvertieren.	Autorisierung der PHP-Anwendung.
Kern-Engine	`nextpdf/nextpdf`	Optional die konvertierten PDF-Daten importieren oder zusammenführen.	Office-Konvertierung.

Laufzeit-Lebenszyklus

Phase	Verhalten	Entwickleraktion
Erstellung der Konfiguration	API-URL, Timeout, maximale Größe, API-Schlüssel und Pins werden geladen.	Halten Sie Dienst-URL und Token aus dem Quellcode heraus.
Eingabevalidierung	Dateipfad, Dateigröße, Dateiname, Erweiterung und URL-Sicherheit werden geprüft.	Nicht unterstützte Eingabe vor dem Dispatch ablehnen.
Aufbau des Payloads	`GotenbergConvertPayload` baut Multipart-Formulardaten auf.	Bewahren Sie den ursprünglichen Dateinamen nur auf, wenn dies sicher ist.
Dienstanfrage	Die Brücke sendet die Anfrage an `/forms/libreoffice/convert`.	Timeout und Transport-Policy konfigurieren.
Parsen des Ergebnisses	`GotenbergResponseParser::parse()` liefert PDF-Bytes und Metadaten.	Behandeln Sie Nicht-PDF- oder Fehlerantworten als Konvertierungsfehler.

Empfohlene Anwendungsstruktur

Pfad	Zweck
`app/Pdf/Conversion/*`	Anwendungs-Wrapper um `GotenbergBridge`.
`app/Pdf/Uploads/*`	Upload-Validierung, Speicherung und Dateinamen-Policy.
`app/Pdf/ConversionPolicy/*`	Policy für Größe, Format und Dienstauswahl.
`tests/Pdf/Conversion/*`	Tests für Format, Datei, Dienst und Transport.

Halten Sie die Dateivalidierung von der Konvertierung getrennt. Ein Konvertierungsdienst sollte bereits autorisierte Eingaben erhalten und sich als zusätzliche Verteidigungsebene dennoch auf die Paketvalidierung stützen.

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

Konvertierungsmuster

Muster	API	Anwendung, wenn	Einschränkung
Dateipfad konvertieren	`GotenbergBridge::convertFile()`	Das Dokument ist bereits auf der Festplatte gespeichert.	Der Pfad muss lesbar und durch die Policy freigegeben sein.
In-Memory-Bytes konvertieren	`GotenbergBridge::convertString()`	Die Anwendung hat bereits Bytes aus einem Upload oder Objektspeicher.	Der Dateiname steuert weiterhin die Formaterkennung.
Payload direkt aufbauen	`GotenbergConvertPayload`	Tests oder eigener Transportcode benötigen Multipart-Bytes.	Halten Sie die Boundary-Generierung außerhalb der Benutzereingabe.
Antwort direkt parsen	`GotenbergResponseParser::parse()`	Ein eigener HTTP-Aufruf soll dennoch das Parsen aus dem Paket nutzen.	Das erwartete `OfficeFormat` muss übergeben werden.

Health und Readiness

GotenbergBridge::isAvailable() ist ein Readiness-Signal. Es sollte nicht der einzige Laufzeitschutz sein. Ein Dienst kann bei der Readiness-Prüfung verfügbar sein und dennoch bei der nächsten Konvertierung fehlschlagen.

Prüfung	Zweck	Betriebshinweis
Gültigkeit der Konfiguration	Fehlende API-URL erkennen.	Beim App-Start oder bei Deployment-Prüfungen ausführen.
`/health`-Verfügbarkeit	Erreichbaren Dienst erkennen.	Für Readiness-Dashboards verwenden.
Konvertierung eines kleinen Fixtures	Defektes LibreOffice oder eine Dienstregression erkennen.	In geplanten Smoke-Tests ausführen, nicht bei jeder Anfrage.
Timeout-Überwachung	Langsames Dienstverhalten erkennen.	Nach Format und Dateigröße erfassen.

Erweiterungspunkte

Erweiterungspunkt	Verwende es für	Einschränkung
PSR-18-`ClientInterface`	Eigenes Verhalten des HTTP-Clients.	Muss der PSR-18-Semantik für response/exception folgen.
PSR-17-Factories	Erzeugung von Request und Stream.	Für den Aufbau der Brücke erforderlich.
`HtmlSecurityPolicyInterface`	Policy auf Parse-Ebene für HTML-Eingaben.	Ergänzt die Gotenberg-Sicherheits-Policy.
`ResponseFactoryInterface`	Antwortkonstruktion für den gepinnten cURL-Transport.	Nur erforderlich, wenn der Transportpfad des Pakets genutzt wird.
`GotenbergSecurityPolicy`	Validierung von URL, Dateigröße, Dateiname und Pin.	Halten Sie die Autorisierung der Anwendung außerhalb dieser Schicht.

Entwicklungs-Workflow

Beginnen Sie in Tests mit convertString(), damit Fixtures explizit sind.
Fügen Sie convertFile() erst hinzu, nachdem die Dateisystempfade kontrolliert sind.
Halten Sie die maximale Dateigröße unter den Limits von Dienst und Infrastruktur.
Verwenden Sie isAvailable() für Readiness-Signale, nicht als Ersatz für die Fehlerbehandlung.
Protokollieren Sie Dateiname, Format, Größe, Status und Dauer. Protokollieren Sie keine Dokument-Bytes.
Fügen Sie Tests für Timeout und Fehlermodi hinzu, bevor Sie Upload-Endpunkte freigeben.

Fehlerbehandlung

Fehler	Wo er behandelt werden sollte	Empfohlene Reaktion
Nicht unterstützte Erweiterung	Formaterkennung.	Vor dem Dienst-Dispatch ablehnen.
Unsicherer Dateiname	Sicherheits-Policy.	Ablehnen und die Namenskonvention für Uploads normalisieren.
Zu große Datei	Upload-Policy und Paketvalidierung.	Ablehnen, bevor große Payloads gelesen oder gesendet werden.
Gotenberg nicht verfügbar	Brückengrenze.	Falls angebracht, einen wiederholbaren Anwendungsfehler zurückgeben.
Nicht-PDF-Antwort	Antwort-Parser.	Als Konvertierungsfehler behandeln und den Dienststatus erfassen.
Fehler bei der Pin- oder URL-Validierung	Transport-Policy.	Fail closed und Operatoren alarmieren.

Sichere Voreinstellungen

Anliegen	Voreinstellung	Wann überschreiben
Timeout	`30` Sekunden.	Erhöhen Sie ihn erst, nachdem Sie die reale Dienstlatenz gemessen haben.
Maximale Dateigröße	`52,428,800` Bytes.	Für öffentliche oder mandantenfähige Endpunkte niedriger ansetzen.
API-Schlüssel	Leer.	Für private Gotenberg-Deployments setzen.
Unterstützte Formate	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	Fügen Sie Formate nur hinzu, wenn `OfficeFormat` und der Parser sie unterstützen.
Pin-Sets	Leer.	Fügen Sie Pins mit Backup-Pins und einem Rotationsverfahren hinzu.

Test-Checkliste

Format-Tests decken unterstützte und nicht unterstützte Erweiterungen ab.
Datei-Tests decken fehlende, nicht lesbare, zu große und unsichere Dateinamen ab.
Dienst-Tests decken Nicht-2xx-Antworten, ungültige Antwort-Bodys und Transport-Exceptions ab.
Sicherheits-Tests decken private oder ungültige Dienst-URLs ab, wenn die Policy sie verbietet.
Timeout-Tests stellen sicher, dass der konfigurierte Timeout an den Transport übergeben wird.
Fixture-Tests halten Beispieldokumente klein und nicht sensibel.