NextPDF Gotenberg installieren

Auf einen Blick

Die Installation der Bridge umfasst zwei Teile: das PHP-Paket und seine PSR-HTTP-Abhängigkeiten, die Sie mit Composer installieren, sowie den Gotenberg-Dienst, den das Paket aufruft. Die Bridge führt die Konvertierung durch, indem sie die Arbeit an diesen Dienst übergibt. Solange keine Gotenberg-Instanz erreichbar ist, kann sie daher nichts konvertieren.

Richten Sie beide Teile ein, bevor Sie Konvertierungscode schreiben.

Anforderungen

Anforderung	Einschränkung	Warum
PHP	>=8.4 <9.0	Das Paket deklariert diesen Bereich in composer.json.
NextPDF Core	^3.0	Direkte Abhängigkeit, deklariert in composer.json.
PSR-18-HTTP-Client	^1.0	Die Bridge sendet Anfragen über ein injiziertes Psr\Http\Client\ClientInterface.
PSR-17-HTTP-Factories	^1.1	Die Bridge erstellt Anfragen und Streams über injizierte PSR-17-Factories.
PSR-3-Logger	^3.0 (optional)	Für Debug-Logging auf Anfrageebene kann ein Logger injiziert werden.
Gotenberg-Dienst	Über HTTPS erreichbar	Die Konvertierung wird vom externen Dienst durchgeführt, nicht von diesem Paket.

Die Bridge bündelt weder einen PSR-18-Client noch PSR-17-Factories. Die Implementierungen wählen Sie selbst aus. Sie können beispielsweise einen Guzzle-basierten Client mit seinen PSR-17-Factories kombinieren oder den Symfony-HTTP-Client mit nyholm/psr7 verwenden. Jede Implementierung, die den relevanten PSR-Verträgen entspricht, funktioniert, da die Bridge ausschließlich von Schnittstellen abhängt und nicht von einer bestimmten Bibliothek.

Schritt 1 — das Paket installieren

Fügen Sie das Paket mit Composer hinzu:

composer require nextpdf/gotenberg

Dadurch werden nextpdf/core ^3.0 sowie die PSR-HTTP-Verträge psr/http-client, psr/http-factory und psr/log aufgelöst. Ein konkreter HTTP-Client wird dabei nicht installiert.

Schritt 2 — einen PSR-18-Client und PSR-17-Factories installieren

Installieren Sie einen PSR-18-Client und einen passenden Satz PSR-17-Factories. Mit Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Alternativ mit dem Symfony-HTTP-Client und Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

Diese Komponenten übergeben Sie der Bridge als Konstruktorargumente. Einen HTTP-Client erstellt sie nie selbst. Die Wahl liegt daher vollständig bei Ihnen und erfolgt beim Zusammensetzen der Bridge. Die Konstruktorform finden Sie unter /integrations/gotenberg/configuration/, ein vollständiges Verdrahtungsbeispiel unter /integrations/gotenberg/quickstart/.

Schritt 3 — einen Gotenberg-Dienst einrichten

Da die Bridge die LibreOffice-Konvertierungsroute von Gotenberg aufruft, benötigen Sie eine Gotenberg-Instanz, die die Bridge erreichen kann. Das Upstream-Projekt veröffentlicht ein Container-Image. Der kanonische Befehl für die lokale Entwicklung lautet:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Damit wird Gotenberg auf Port 3000 über einfaches HTTP bereitgestellt; das eignet sich nur für die lokale Entwicklung. Die Bridge erfordert HTTPS für die konfigurierte API-URL. Sie lehnt einfaches http:// ab, bevor sie eine Anfrage sendet. Für alles, was über ein lokales Experiment hinausgeht, platzieren Sie Gotenberg hinter einem TLS-terminierenden Reverse-Proxy oder Service-Mesh und richten Sie die Bridge anschließend auf den HTTPS-Endpunkt aus. /integrations/gotenberg/security-and-operations/ behandelt Produktionsbereitstellung, Netzwerkexposition und Authentifizierung.

Das hier gezeigte Image-Tag (gotenberg/gotenberg:8) gehört zur Upstream- Hauptlinie von Gotenberg. Die README dieses Projekts und die Integrations- Baseline verweisen auf diese Linie. Pinnen Sie in der Produktion ein bestimmtes Patch- Tag, anstatt einem beweglichen Haupt-Tag zu folgen. Gleichen Sie außerdem die Routenpfade (/forms/libreoffice/convert, /health) mit der Gotenberg- Version ab, die Sie bereitstellen. Die Bridge geht von diesen beiden Pfaden aus und trifft keine weiteren Annahmen über den Dienst.

Schritt 4 — die Verdrahtung überprüfen

Zu diesem Zeitpunkt sind das Paket und ein HTTP-Client installiert, und Gotenberg ist über HTTPS erreichbar. Bevor Sie eine echte Konvertierung ausführen, prüfen Sie mit der integrierten Health-Probe, ob der Dienst für die Bridge erreichbar ist:

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
);

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() validiert zunächst die konfigurierte URL. Sie gibt false für eine leere, nicht über HTTPS erreichbare oder auf eine private Adresse verweisende URL zurück, ohne Netzwerkverkehr zu erzeugen. Anschließend sendet sie eine HEAD-Anfrage an <apiUrl>/health und meldet den Dienst als verfügbar, wenn der Statuscode unter 500 liegt. Ein Netzwerkfehler wird abgefangen und als nicht verfügbar gemeldet, statt als Ausnahme geworfen zu werden.

Versionshinweis

Diese Dokumentation beschreibt das Paket in seiner ^3.0-Linie. Diese Linie entspricht der Anforderung in composer.json und der Support-Matrix in SECURITY.md, nach der 3.x unterstützt wird und 2.x nicht. Frühere 0.x-Verweise in den Skeleton-Seiten des Repositorys stammen aus der Zeit vor der 3.0-Linie; die Einschränkung in composer.json hat ihnen gegenüber Vorrang.

Siehe auch

• /integrations/gotenberg/overview/ — was die Bridge tut und welche Formate sie konvertiert.
• /integrations/gotenberg/configuration/ — alle Konstruktorargumente und Konfigurationsfelder.
• /integrations/gotenberg/quickstart/ — eine vollständige, ausführbare erste Konvertierung.
• /integrations/gotenberg/security-and-operations/ — wie die Gotenberg-Abhängigkeit sicher betrieben wird.
• /integrations/gotenberg/boot-and-discovery/ — Framework-Auto-Wiring.