Gotenberg-API-Referenz

Auf einen Blick

Das Gotenberg-Paket stellt mit GotenbergBridge eine Service-Bridge bereit, die ein Office-Dokument (docx, xlsx, pptx, odt, ods, odp) in PDF umwandelt, indem sie das Dokument per POST an einen externen Gotenberg-Service sendet. Dazu gehören die unterstützenden Value Objects, die Sie auslesen oder übergeben: GotenbergConfig (der unveränderliche Servicedeskriptor mit den Limits), OfficeFormat (das Enum der unterstützten Formate), GotenbergConvertPayload (der Multipart-Request-Body) und GotenbergConvertResult (die geparste PDF-Antwort). Die zweite Ebene, GotenbergSecurityPolicy, GotenbergResponseParser und PinnedCurlTransport, bildet die interne Infrastruktur für Validierung, Parsing und gepinnten Transport, die die Bridge nutzt. Sie verwenden sie nur, wenn Sie eigenen Transport- oder Testcode schreiben.

Starten Sie hier: Konstruieren Sie eine GotenbergConfig mit Ihrer HTTPS-Service-URL und verdrahten Sie sie in eine GotenbergBridge mit Ihrem PSR-18-Client und Ihren PSR-17-Factories. Rufen Sie dann convertFile() oder convertString() auf und lesen Sie pdfData aus dem zurückgegebenen GotenbergConvertResult.

Häufige Aufgaben

Dies sind die häufigsten praktischen Aufgaben mit diesem Paket, jeweils mit einem geprüften, lauffähigen Snippet.

Eine Datei auf der Festplatte in PDF umwandeln

Richten Sie die Bridge auf einen Pfad aus; das Format wird aus der Dateiendung erkannt.

<?php

declare(strict_types=1);

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: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    responseFactory: $psrResponseFactory,
);

$result = $bridge->convertFile('/path/to/report.docx');

\file_put_contents('/path/to/report.pdf', $result->pdfData);

Was der Aufruf tut: Er validiert URL, Pfad, Größe und Dateinamen, sendet einen einzigen Multipart-Request und schreibt die zurückgegebenen PDF-Bytes auf die Festplatte.

Bytes im Arbeitsspeicher in PDF umwandeln

Nutzen Sie convertString(), wenn die Bytes bereits vorliegen; der Dateiname steuert die Formaterkennung.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

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

Was der Aufruf tut: Er erkennt xlsx aus dem Dateinamen, wandelt die Bytes um und bestätigt, dass das Ergebnis mit der Signatur %PDF beginnt, bevor Sie es verwenden.

Die Service-Bereitschaft vor dem Umwandeln prüfen

Machen Sie die Umwandlung von isAvailable() abhängig; die Methode validiert die URL ohne Traffic und sendet anschließend einen einzigen HEAD an /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Was der Aufruf tut: Er liefert false (wirft nie) bei einer leeren, nicht-HTTPS- oder privaten URL sowie bei jedem Netzwerkfehler, sodass Sie früh abbrechen können, bevor Sie eine Umwandlung anstoßen.

Bridge

Diese Tabelle beschreibt die Oberfläche der Bridge. Verwenden Sie sie, wenn Sie GotenbergBridge konstruieren oder ihre Umwandlungs- und Bereitschaftsmethoden aufrufen.

Symbol	Parameter	Standardverhalten	Rückgabewert	Wirft oder scheitert mit	Hinweise
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Config, PSR-18-Client, PSR-17-Factories, optionaler Logger, optionale HTML-Policy, optionale Response-Factory.	Verwendet `DefaultHtmlSecurityPolicy`, wenn keine Policy übergeben wird.	`GotenbergBridge`	Fehler bei der Container-Verdrahtung.	Die Response-Factory aktiviert den gepinnten cURL-Transport, wenn Pinning benötigt wird.
`GotenbergBridge::convertFile(string $filePath)`	Dateisystempfad zu einem Office-Dokument.	Verwendet die Dateiendung zur Formaterkennung.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` bei nicht unterstütztem Format.	Löst den realen Pfad auf und prüft Lesbarkeit, Größe und Dateinamen.
`GotenbergBridge::convertString(string $content, string $fileName)`	Rohe Bytes und ursprünglicher Dateiname.	Verwendet die Dateiendung zur Formaterkennung.	`GotenbergConvertResult`	Wie `convertFile`.	Verwenden Sie dies, wenn die Anwendung die Datei-Bytes bereits hält.
`GotenbergBridge::isAvailable()`	keine.	HEAD-Request an `/health`, wenn die Config gültig ist.	`bool`	Liefert `false` bei Fehlern.	Nur ein Bereitschaftssignal.
`GotenbergBridge::getHtmlSecurityPolicy()`	keine.	Liefert die konfigurierte Parse-Layer-Policy.	`HtmlSecurityPolicyInterface`	keine erwartet.	Ergänzt die Sicherheits-Policy auf Transportebene.

Konfiguration und Payloads

Diese Tabelle behandelt die Value Objects, die Sie von Hand erstellen: den Servicedeskriptor GotenbergConfig sowie die Request- und Response-Träger GotenbergConvertPayload/GotenbergConvertResult, wenn Sie feinere Kontrolle benötigen, als die beiden Convert-Einstiegspunkte bieten.

Symbol	Parameter	Standardverhalten	Rückgabewert	Wirft oder scheitert mit	Hinweise
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	API-URL, Timeout, maximale Dateigröße, Bearer-Token, Pin-Sets.	Eine leere URL ist ungültig; die maximale Standardgröße beträgt 50 MiB.	`GotenbergConfig`	keine erwartet.	Halte den API-Schlüssel geheim.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, Pin-Arrays.	Fehlende optionale Werte verwenden die Konstruktorstandardwerte.	`GotenbergConfig`	keine erwartet.	Stringlisten ignorieren Nicht-String-Werte.
`GotenbergConfig::isValid()`	keine.	Gültig, wenn die API-URL nicht leer ist.	`bool`	keine erwartet.	Die URL-Sicherheit wird vor jeglichem Netzwerk-I/O validiert.
`GotenbergConfig::allPublicKeyPins()`	keine.	Kombiniert primäre und Backup-Pins.	`list<string>`	keine erwartet.	Eine leere Liste deaktiviert das Pinning.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Dateiname, Bytes, Format, Ausrichtungsflag, Seitenbereiche.	Hochformat; alle Seiten.	`GotenbergConvertPayload`	keine erwartet.	Der Payload wird in Multipart-Form-Data umgewandelt.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Multipart-Boundary.	Bindet das Seitenbereichsfeld nur ein, wenn es nicht leer ist.	`string`	keine erwartet.	Die Boundary wird von der Bridge generiert.
`GotenbergConvertPayload::contentType(string $boundary)`	Multipart-Boundary.	Verwendet `multipart/form-data`.	`string`	keine erwartet.	Hängen Sie dies als `Content-Type` des Requests an.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Umgewandelte PDF-Bytes, Quellformat, optionale Renderdauer.	Die Renderdauer beträgt `0.0`, wenn sie nicht gemessen wurde.	`GotenbergConvertResult`	keine erwartet.	Zurückgegeben von `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	keine.	Gültig, wenn die umgewandelten PDF-Bytes nicht leer sind und wie PDF-Daten aussehen.	`bool`	keine erwartet.	Prüfen Sie dies, bevor Sie das Ergebnis persistieren oder streamen.
`GotenbergConvertResult::size()`	keine.	Zählt die umgewandelten PDF-Bytes.	`int`	keine erwartet.	Verwenden Sie dies für Kontingente, Telemetrie und Antwortlimits.

Office-Formate

Diese Tabelle ist für das Enum OfficeFormat. Verwenden Sie sie, wenn Sie eine Endung auf ein Format abbilden, ihren Upload-MIME-Typ auslesen oder prüfen müssen, welche sechs Formate unterstützt werden.

Symbol	Parameter	Standardverhalten	Rückgabewert	Wirft oder scheitert mit	Hinweise
`OfficeFormat::fromExtension(string $ext)`	Dateiendung mit oder ohne führenden Punkt.	Abgleich ohne Berücksichtigung der Groß-/Kleinschreibung.	`OfficeFormat`	`ValueError` bei nicht unterstützter Endung.	Unterstützte Werte: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	keine.	Bildet den Enum-Case auf den Upload-MIME-Typ ab.	`string`	keine erwartet.	Wird im Multipart-Datei-Teil verwendet.
`OfficeFormat::extension()`	keine.	Liefert den hinterlegten Wert.	`string`	keine erwartet.	Nützlich für Diagnostik und Dateinamen.

Sicherheit, Parsing und Transport

Diese Tabelle beschreibt die interne Infrastruktur, die die Bridge für Sie nutzt. Verwenden Sie sie nur, wenn Sie eigenen Transport, einen maßgeschneiderten HTTP-Aufruf, der trotzdem das Paket-Parsing nutzen soll, oder Low-Level-Diagnostik für Sicherheit und Pinning schreiben.

Symbol	Parameter	Standardverhalten	Rückgabewert	Wirft oder scheitert mit	Hinweise
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	API-Basis-URL.	Parst und validiert das Ziel vor jeglichem Netzwerk-I/O.	`array`	`RuntimeException` bei unsicheren oder ungültigen URLs.	Hält SSRF-artige Endpunktfehler vom Umwandlungscode fern.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Host und Liste der gepinnten IPs.	Verifiziert die DNS-Pin-Erwartungen.	`void`	`RuntimeException`, wenn die Pins veraltet oder ungültig sind.	Nutze dies in gepinnten Deployments und für betriebliche Diagnostik.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Tatsächliche Größe und konfiguriertes Maximum.	Akzeptiert Dateien, die das konfigurierte Limit erreichen oder darunter liegen.	`void`	`RuntimeException`, wenn die Datei zu groß ist.	Erzwingen Sie dies vor dem Aufbau des Requests.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Ursprünglicher Dateiname.	Weist unsichere oder nicht unterstützte Dateinamensformen zurück.	`void`	`RuntimeException` bei ungültigen Namen.	Verhindert fehlerhafte Multipart-Dateinamen.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	PSR-7-Response und erwartetes Office-Format.	Extrahiert die umgewandelten PDF-Bytes aus einer erfolgreichen Response.	`GotenbergConvertResult`	`GotenbergConvertException` bei fehlgeschlagenen Responses oder ungültiger PDF-Ausgabe.	Zentraler Parser für Datei- und String-Umwandlung.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	PSR-17-Factories, gepinnte IPs, gepinnte Public Keys, Timeout.	Keine Pins; Timeout von 30 Sekunden.	`PinnedCurlTransport`	keine erwartet.	Verwenden Sie dies nur, wenn Pinning auf cURL-Ebene erforderlich ist.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	PSR-7-Request.	Sendet über cURL mit konfiguriertem Timeout und Pinning-Kontrollen.	`ResponseInterface`	`GotenbergConvertException` bei cURL-/Transportfehler.	Verwenden Sie dies, wenn Pinning nicht an einen anderen HTTP-Client delegiert werden kann.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Request, Host und Port.	Baut das cURL-Options-Array, das `sendRequest()` verwendet.	`array`	Fehler bei ungültigem Request oder ungültiger Pin-Konfiguration.	Low-Level-Diagnostik und Test-Hook.

Entwicklungshinweise

Behandeln Sie Gotenberg als Grenze zu einem externen Service. Konfigurieren Sie Timeout, Größe, URL und Pin-Policy bewusst.
convertFile() liest die gesamte Datei in den Arbeitsspeicher, bevor der Request aufgebaut wird.
Protokollieren Sie Metadaten wie Dateiname und Inhaltslänge, nicht den Dateiinhalt.