NextPDF-Gotenberg-Schnellstart

Auf einen Blick

Diese Anleitung konvertiert eine .docx-Datei in ein PDF. Am Ende haben Sie drei Dinge: eine funktionierende Bridge-Instanz, eine geprüfte Dienstverbindung und ein PDF auf der Festplatte. Das vollständige Programm finden Sie im Repository unter examples/convert-office-to-pdf.php. Die folgenden Codeausschnitte sind Auszüge daraus.

Diese Seite ist ein Tutorial und zeigt daher zunächst den Idealfall. Produktionsaspekte wie die Beschaffung von Geheimnissen, Wiederholungsversuche, Timeouts und Observability werden unter /integrations/gotenberg/production-usage/ behandelt.

Bevor Sie beginnen

Prüfen Sie diese drei Punkte:

1. composer require nextpdf/gotenberg wurde ausgeführt, und ein PSR-18-Client sowie PSR-17-Factories sind installiert. Siehe /integrations/gotenberg/install/.
2. Ein Gotenberg-Dienst ist über HTTPS erreichbar. Einfaches http:// lehnt die Bridge ab, bevor eine Anfrage den Prozess verlässt.
3. Sie haben eine Beispieldatei in einem dieser Formate: .docx, .xlsx, .pptx, .odt, .ods oder .odp. Andere Erweiterungen werden mit einem ValueError abgewiesen.

Schritt 1 – Beschreiben Sie den Dienst

GotenbergConfig ist ein unveränderliches Value Object. Mindestens erforderlich ist die HTTPS-Basis-URL Ihres Gotenberg-Dienstes:

use NextPDF\Gotenberg\GotenbergConfig;

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

timeout ist der Übertragungs-Timeout in Sekunden, den der cURL-gepinnte Transport anwendet. apiKey wird, sofern nicht leer, als Authorization: Bearer <token> gesendet. Lassen Sie apiKey leer, wenn Ihr Gotenberg-Deployment keinen Token erfordert.

Schritt 2 – Verdrahten Sie die Bridge

Die Bridge erhält die Konfiguration sowie ihre PSR-Abhängigkeiten. Injizieren Sie außerdem eine responseFactory, um den cURL-Transport mit DNS-Pinning und TLS-Pinning zu aktivieren:

use NextPDF\Gotenberg\GotenbergBridge;

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

Die Bridge erstellt niemals selbst einen HTTP-Client. Verwenden Sie den PSR-18-Client und die PSR-17-Factories, die Sie installiert haben. Die Beispieldatei zeigt die Guzzle-Verdrahtung in einem Kommentar.

Schritt 3 – Prüfen Sie die Verfügbarkeit

Prüfen Sie den Dienst, bevor Sie etwas konvertieren. Die Prüfung validiert die URL ohne Netzwerkverkehr und sendet anschließend ein HEAD an <apiUrl>/health:

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

isAvailable() gibt false zurück (und löst niemals eine Ausnahme aus), wenn die URL leer ist, kein HTTPS verwendet, auf eine private Adresse verweist oder ein Netzwerkfehler auftritt. Ein Status unter 500 von /health bedeutet, dass der Dienst verfügbar ist.

Schritt 4 – Konvertieren

convertFile() nimmt einen Pfad auf der Festplatte entgegen. Der Pfad wird kanonisiert, um Traversal zu blockieren. Die Erweiterung wird einem unterstützten Format zugeordnet. Größe und Dateiname werden geprüft. Anschließend wird eine Multipart-Anfrage an <apiUrl>/forms/libreoffice/convert gesendet:

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

Um Bytes zu konvertieren, die bereits im Speicher liegen, verwenden Sie convertString(). Übergeben Sie den ursprünglichen Dateinamen, damit die Bridge die Erweiterung erkennen kann:

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

Schritt 5 – Verwenden Sie das Ergebnis

Das Ergebnis enthält drei Dinge: die PDF-Bytes, das Quellformat und eine Gültigkeitsprüfung:

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() ist true, wenn der Body nicht leer ist und mit %PDF beginnt. size() ist die Byte-Länge. Ab hier ist das PDF ein normaler Stream, den Sie zur Nachbearbeitung an NextPDF übergeben können.

Das vollständige Programm

Das vollständige, ausführbare Programm finden Sie unter examples/convert-office-to-pdf.php im Paket-Repository. Es deckt das Parsen von Argumenten, die umgebungsgesteuerte Konfiguration, die Health-Prüfung, eine umfassende Fehlerbehandlung und das Schreiben ab. Führen Sie es so aus:

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

Wie geht es weiter

• /integrations/gotenberg/configuration/ – alle Optionen und die Regeln zur Transportauswahl.
• /integrations/gotenberg/production-usage/ – Geheimnisse, Wiederholungsversuche, Timeouts, Logging, Nebenläufigkeit.
• /integrations/gotenberg/troubleshooting/ – jede Ausnahme, die dieser Code auslösen kann, und ihre Bedeutung.
• /integrations/gotenberg/integration/ – Steuerung einer NextPDF-Rendering-Pipeline über den Dienst.