NextPDF Gotenberg konfigurieren

Auf einen Blick

Die Konfiguration verteilt sich auf zwei Stellen. Zum einen auf das unveränderliche Wertobjekt GotenbergConfig, das den Dienst und seine Grenzwerte beschreibt. Zum anderen auf den Konstruktor GotenbergBridge, der die PSR-HTTP-Kollaboratoren einbindet. Beide verwenden explizite Konstruktorinjektion. Es gibt keinen globalen Zustand, kein Auslesen von Umgebungsvariablen innerhalb des Pakets und keinen versteckten Standardendpunkt.

Das Konfigurationsobjekt

GotenbergConfig ist ein final readonly-Wertobjekt. Erstellen Sie es direkt mit benannten Argumenten oder aus einem assoziativen Array mit GotenbergConfig::fromArray().

Felder

Feld	Typ	Standard	Auswirkung
apiUrl	string	''	Basis-URL des Gotenberg-Dienstes. Erforderlich: Ein leerer Wert macht die Konfiguration ungültig; jede Konvertierung schlägt sofort fehl. Muss HTTPS verwenden.
timeout	int	30	Festes Übertragungstimeout in Sekunden. Wird vom cURL-gepinnten Transport angewendet, wenn dieser Transport ausgewählt ist.
maxFileSize	int	52_428_800	Maximale Eingabegröße in Byte (50 MiB). Eingaben, die diesen Wert überschreiten, werden vor jeder Anfrage abgelehnt.
apiKey	string	''	Bearer-Token. Ist der Wert nicht leer, wird er als Authorization: Bearer <token>-Header gesendet. Mit #[\SensitiveParameter] markiert, sodass er in Stacktraces redigiert wird.
pinnedPublicKeys	list<string>	[]	Primäre TLS-SPKI-Pins in der Form sha256/<base64>. Eine leere Liste deaktiviert das Pinning.
backupPublicKeys	list<string>	[]	Backup-TLS-SPKI-Pins; sie werden getrennt gehalten, damit die Rotation unabhängig validiert werden kann.

Direkte Konstruktion

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

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

Konstruktion aus einem Array

fromArray() akzeptiert snake_case-Schlüssel und ignoriert fehlerhafte Werte, anstatt eine Ausnahme zu werfen. Ein Wert für api_url, der kein String ist, wird zu ''. Ein Wert für timeout, der kein Integer ist, fällt auf 30 zurück. Ein Wert für max_file_size, der kein Integer ist, fällt auf den Standardwert von 50 MiB zurück. Pin-Listen, die keine Arrays sind, werden zu []. Einträge in den Pin-Arrays, die keine Strings sind, werden verworfen.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Dieses tolerante Parsing ist beabsichtigt. Es erlaubt Ihnen, ein Framework-Konfigurations-Array direkt einzuspeisen, ohne eine Vorabvalidierungsschicht vorzuschalten, und erzeugt dennoch ein sauber typisiertes Objekt. Es validiert nicht, dass die URL erreichbar ist oder dass die Pins korrekt sind. Diese Prüfungen erfolgen zur Konvertierungszeit.

Gültigkeit

isValid() gibt nur dann true zurück, wenn apiUrl eine nicht-leere Zeichenkette ist. Es führt keine Netzwerk- oder Schemaprüfungen durch. Die Prüfung auf HTTPS und private Adressen erfolgt innerhalb der Sicherheitsrichtlinie zur Konvertierungszeit. Eine ungültige Konfiguration bewirkt, dass convertFile() und convertString() eine GotenbergConvertException mit der Meldung Invalid Gotenberg configuration: apiUrl is empty werfen. Außerdem gibt isAvailable() bei ungültiger Konfiguration ohne Netzwerkaufruf false zurück.

Der Bridge-Konstruktor

GotenbergBridge nimmt die Konfiguration und die PSR-Kollaboratoren entgegen:

Argument	Typ	Erforderlich	Auswirkung
config	GotenbergConfig	ja	Der oben beschriebene Dienstdeskriptor und die Grenzwerte.
httpClient	Psr\Http\Client\ClientInterface	ja	Der PSR-18-Client, der für die Health-Probe und als Fallback-Transport verwendet wird.
requestFactory	Psr\Http\Message\RequestFactoryInterface	ja	Erstellt die PSR-7-Anfrage.
streamFactory	Psr\Http\Message\StreamFactoryInterface	ja	Erstellt den Anfrage-Body-Stream.
logger	Psr\Log\LoggerInterface|null	nein (Standard null)	Wenn angegeben, wird pro Konvertierungsanfrage ein Eintrag auf debug-Ebene protokolliert.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	nein	Standardmäßig gilt die Standard-HTML-Sicherheitsrichtlinie des Kerns. Richtlinie auf Parse-Ebene; ergänzt die Richtlinie auf Transport-Ebene.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	nein (Standard null)	Erforderlich, um den cURL-gepinnten Transport zu aktivieren. Ohne ihn verwendet die Bridge immer den injizierten PSR-18-Client.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Transportauswahl

Die Bridge verfügt über zwei Transporte und wählt für jede Konvertierungsanfrage einen davon aus:

• cURL-gepinnter Transport — wird verwendet, wenn eine responseFactory injiziert wurde und etwas für das Pinning vorhanden ist (die URL wurde zu einer oder mehreren IPs aufgelöst, oder SPKI-Pins sind konfiguriert). Dieser Transport bindet die aufgelöste Adressmenge mit CURLOPT_RESOLVE. Er erzwingt SPKI-Pinning mit CURLOPT_PINNEDPUBLICKEY, wenn Pins vorhanden sind. Er verifiziert Peer und Host (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Er wendet das konfigurierte Timeout an und deaktiviert das Folgen von Weiterleitungen (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Injizierter PSR-18-Client — wird in jedem anderen Fall verwendet, auch wenn die API-URL ein reines öffentliches IP-Literal ist (kein DNS zum Pinnen) und keine SPKI-Pins konfiguriert sind, oder wenn keine responseFactory angegeben wurde.

Die praktische Konsequenz: Um DNS-Rebinding-resistente Verbindungen und TLS-Pinning zu erhalten, injizieren Sie eine responseFactory und konfigurieren Sie Pins. Die Health-Probe verwendet unabhängig von der Transportauswahl immer den injizierten PSR-18-Client.

TLS-Public-Key-Pinning

Das Pinning folgt dem SHA-256-SPKI-Fingerabdruckmodell. Jeder Pin ist eine Zeichenkette der Form sha256/<base64-encoded-spki-hash>. Der Transport akzeptiert auch die cURL-native Form sha256//<base64> und konvertiert die Variante mit einfachem Schrägstrich dorthin. Jedes andere Präfix löst eine InvalidSpkiPinException aus.

allPublicKeyPins() gibt die deduplizierte Vereinigung von pinnedPublicKeys und backupPublicKeys zurück. Die TLS-Schicht akzeptiert ein Zertifikat, dessen SPKI-Hash mit einem beliebigen Mitglied dieser kombinierten Menge übereinstimmt. Im Betrieb sollten Sie mindestens einen Backup-Pin konfigurieren, damit eine geplante Zertifikats- oder Schlüsselrotation die Bridge nicht vom Dienst aussperrt, während der neue Schlüssel ausgerollt wird. Wenn Sie die Backup-Liste getrennt von der primären Liste halten, können Sie den Backup-Pin unabhängig vom aktiven Pin validieren und rotieren. Das Rotationsverfahren finden Sie unter /integrations/gotenberg/security-and-operations/.

Konvertierungsoptionen pro Anfrage

Der Multipart-Payload-Typ (GotenbergConvertPayload) enthält zusätzlich zur Datei zwei optionale Gotenberg-Konvertierungsoptionen:

• landscape (bool, Standard false) — wird als landscape-Formularfeld mit "true" oder "false" gesendet.
• nativePageRanges (string, Standard '') — wird nur dann als nativePageRanges-Formularfeld gesendet, wenn es nicht leer ist; akzeptiert die Bereichssyntax von Gotenberg wie 1-3 oder 1,3,5-9.

Die öffentlichen Einstiegspunkte convertFile() und convertString() erstellen den Payload mit den Standardwerten für diese beiden Felder. Die Felder sind Teil des Payload-Vertrags und werden von der Test-Suite geprüft. Setzen Sie sie in Ihrer eigenen Integrationsschicht, wenn Sie Querformat-Ausgabe oder Seitenauswahl benötigen.

Siehe auch

• /integrations/gotenberg/install/ — Installation und Gotenberg-Baseline.
• /integrations/gotenberg/quickstart/ — ein lauffähiges End-to-End-Beispiel.
• /integrations/gotenberg/production-usage/ — Konfigurationsreferenz, Geheimnisse, Timeouts, Wiederholungen.
• /integrations/gotenberg/security-and-operations/ — das vollständige Sicherheitsmodell und die Pin-Rotation.
• /integrations/gotenberg/troubleshooting/ — Bedeutung der einzelnen konfigurationsbezogenen Ausnahmen.