NextPDF-Gotenberg-Integration

Auf einen Blick

Diese Seite zeigt, wie Sie die Bridge mit dem Rest einer Anwendung verbinden. Installieren Sie die Bridge, verdrahten Sie sie und übergeben Sie das konvertierte PDF anschließend an eine NextPDF-Nachbearbeitungspipeline. Die Bridge wandelt ein Office-Dokument in ein PDF um; die Pipeline übernimmt alles, was danach folgt. Diese Seite ist das aufgabenorientierte Gegenstück zu /integrations/gotenberg/boot-and-discovery/, wo erläutert wird, warum die Verdrahtung so aufgebaut ist.

Installation

composer require nextpdf/gotenberg

Dies installiert nextpdf/core ^3.0 und die PSR-HTTP-Verträge als Abhängigkeiten. Installieren Sie einen PSR-18-Client und PSR-17-Factories selbst als separate Pakete. Die Bridge hängt nur von den Schnittstellen ab; die konkreten Bibliotheken wählen Sie. Eine vollständige Installation einschließlich der Einrichtung des Gotenberg-Dienstes über HTTPS finden Sie unter /integrations/gotenberg/install/.

Verdrahtung

Erzeugen Sie die Bridge mit einem Konfigurationsobjekt und den PSR-Kollaboratoren. Übergeben Sie zusätzlich eine Response-Factory, die den Transport mit DNS-Pinning und TLS-Pinning aktiviert:

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,
);

Die Bridge erfordert HTTPS für die konfigurierte URL. Unverschlüsseltes http:// weist sie bereits vor jeder Anfrage ab. Betreiben Sie Gotenberg hinter einer TLS-Terminierung und richten Sie die Bridge auf den HTTPS-Endpunkt aus.

Container-Bindungen

Registrieren Sie drei Komponenten in Ihrem Host-Container. Die erste ist die aus Ihrer Konfigurationsquelle erstellte GotenbergConfig. Die zweite ist Ihr PSR-18-Client zusammen mit Ihren PSR-17-Factories. Die dritte ist GotenbergBridge, die aus diesen Komponenten verdrahtet wird. Dieses Paket bringt keine eigenen Bindungen mit. Die frameworkeigene Registrierung gehört zu den dedizierten Framework-Integrationspaketen. Siehe /integrations/gotenberg/boot-and-discovery/.

Konfiguration

Der Dienstdeskriptor und seine Limits sind vollständig in Feldern von GotenbergConfig abgebildet. Dazu gehören die API-URL, das Timeout, die Größenobergrenze, das Bearer-Token und die TLS-Pins. Die anfragebezogenen Optionen landscape und nativePageRanges sind stattdessen Felder des Payload-Typs. /integrations/gotenberg/configuration/ dokumentiert jedes Feld mit Typ, Standardwert und Wirkung.

Das konvertierte PDF mit einer NextPDF-Pipeline verbinden

Ein typischer End-to-End-Ablauf:

1. Konvertieren Sie das Office-Dokument mit convertFile() oder convertString().
2. Nehmen Sie $result->pdfData, das die rohen PDF-Bytes enthält, und laden Sie den Bytestrom in ein NextPDF-Dokument.
3. Wenden Sie eine Nachbearbeitung an, etwa Seitenmontage, Wasserzeichen, PDF/A-Konvertierung oder digitale Signaturen.

Schritt 3 liegt in der Verantwortung von NextPDF, nicht der Bridge. Das Paket nextpdf/premium bietet Signierung, PDF/A-Profile und Wasserzeichen. Halten Sie Konvertierung und Nachbearbeitung in getrennten Stufen. So können Sie jeden Fehler einzeln diagnostizieren.

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.

Die PAdES-Unterstützung der Pro-Edition umfasst ausschließlich die B-B-Baseline. Sie bietet kein B-T, B-LT oder B-LTA. Das Konvertieren eines Dokuments über diese Bridge impliziert keinerlei Zeitstempel- oder Langzeitvalidierungsfähigkeit.

Smoke-Test

Prüfen Sie nach der Verdrahtung die Integration. Das ist möglich, ohne ein echtes Dokument zu konvertieren:

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

isAvailable() validiert die URL ohne Netzwerkverkehr. Anschließend sendet die Methode ein HEAD an <apiUrl>/health. Konvertieren Sie danach ein bekanntermaßen einwandfreies, kleines Dokument. Damit durchlaufen Sie den vollständigen Multipart-Pfad zu <apiUrl>/forms/libreoffice/convert einschließlich der Antwortvalidierung.

Öffentliche API-Einstiegspunkte

Die öffentliche Oberfläche, die diese Integration verwendet:

• GotenbergConfig — unveränderlicher Dienstdeskriptor und Limits; fromArray() erstellt ihn aus einem Konfigurations-Array.
• GotenbergBridge::convertFile(string $path) — konvertiert eine Datei auf der Festplatte.
• GotenbergBridge::convertString(string $bytes, string $fileName) — konvertiert im Speicher gehaltene Bytes.
• GotenbergBridge::isAvailable() — Bereitschaftsprüfung, die keine Ausnahme wirft.
• GotenbergConvertResult — enthält pdfData, sourceFormat, isValid() und size().
• GotenbergConvertException — der Ausnahmetyp der Konvertierungsschicht.

Den vollständigen Vertrag finden Sie unter /integrations/gotenberg/configuration/ und /integrations/gotenberg/troubleshooting/. Er umfasst die Transportauswahl und den Ausnahmekatalog.

Siehe auch

• /integrations/gotenberg/boot-and-discovery/ — warum die Verdrahtung so aufgebaut ist.
• /integrations/gotenberg/quickstart/ — eine angeleitete erste Konvertierung.
• /integrations/gotenberg/production-usage/ — Secrets, Wiederholungsversuche, Timeouts, Observability.
• /integrations/gotenberg/install/ — Installation des Pakets und des Gotenberg-Dienstes.