NextPDF Gotenberg: bootstrapping en discovery

In het kort

De bridge heeft geen automatisch discoverymechanisme. Je construeert hem als een gewone service met expliciete constructorinjectie: een configuratie-value-object en Hypertext Transfer Protocol (HTTP)-collaborators die zijn gedefinieerd door PHP Standard Recommendation (PSR). Dit package levert geen service provider, bundle of containeruitbreiding en leest zelf geen omgevingsvariabelen. In deze context betekent „discovery” hoe een hostframework die collaborators levert. Die verantwoordelijkheid ligt bij het framework, niet bij dit package.

Hoe discovery voor de bridge werkt

Er is geen automatische discovery. Je construeert hem zelf. GotenbergBridge vereist vier argumenten en accepteert drie optionele argumenten:

Vereist: een GotenbergConfig, een PSR-18-client, een PSR-17-request-factory en een PSR-17-stream-factory.
Optioneel: een PSR-3-logger, een Hypertext Markup Language (HTML)-beveiligingsbeleid (standaard het standaardbeleid van NextPDF core) en een PSR-17-response-factory.

De response-factory activeert het cURL-pinned transport. Als je hem levert en de bridge iets heeft om te pinnen (opgeloste adressen of geconfigureerde SubjectPublicKeyInfo (SPKI)-pins), gebruikt hij het pinning-transport. Laat je hem weg, dan wordt altijd de geïnjecteerde PSR-18-client gebruikt. Het volledige argumentcontract staat in /integrations/gotenberg/configuration/.

Bootvolgorde

Er is geen registratiestap. De levenscyclus is:

De host lost een PSR-18-client en PSR-17-factories op. De hostcontainer doet dit; het package niet.
De applicatie bouwt een GotenbergConfig op uit de eigen configuratiebron. GotenbergConfig::fromArray() accepteert een snake_case-array en vervangt onjuist geformatteerde waarden door standaardwaarden. Valideer de bron in je bootpad, zodat een ontbrekende Uniform Resource Locator (URL)-waarde tijdens de boot faalt en niet per conversie.
De applicatie construeert GotenbergBridge met de config en de collaborators.
De eerste conversie-aanroep voert URL-validatie, server-side request forgery (SSRF)-screening en bestandsnaamscreening uit, en verstuurt de request. Er gebeurt geen werk bij het construeren; de bridge blijft inactief totdat je hem aanroept.

Containerbindings

Dit package levert geen containerbindings. Registreer de bridge als volgt in de container van je hostapplicatie om hem injecteerbaar te maken:

Bind GotenbergConfig vanuit je configuratiebron.
Bind de PSR-18-client en PSR-17-factories aan de implementaties van je keuze.
Bind GotenbergBridge als een service die die dependencies ontvangt.

Framework-native auto-wiring, het publiceren van configuratie en de registratie van een service provider of bundle horen thuis in de specifieke framework-integratiepackages, niet hier. Dit package is bewust framework-onafhankelijk. Het is alleen afhankelijk van PSR-interfaces, dus het werkt met elke container.

Resolutievolgorde van de configuratie

Het package leest zelf geen configuratie. De resolutievolgorde is de volgorde die je applicatie implementeert voordat zij GotenbergConfig::fromArray() of de constructor aanroept. Een gangbare volgorde is omgevingsvariabelen, daarna een gepubliceerd config-bestand, daarna standaardwaarden in de code. Die volgorde is het contract van je applicatie, niet dat van dit package. Wat het package wel definieert, is de standaardwaarde voor elk veld dat ontbreekt in de array die aan fromArray() wordt doorgegeven: lege application programming interface (API)-URL, time-out van 30 seconden, groottelimiet van 50 MiB, lege API-sleutel en lege pinlijsten.

Diagnostiek

Twee ingebouwde signalen bevestigen de wiring:

isAvailable() valideert de URL zonder netwerkverkeer, stuurt vervolgens een HEAD-request naar <apiUrl>/health en meldt beschikbaarheid wanneer de status lager is dan 500. Bij een fout retourneert hij false in plaats van een exception te gooien. Roep hem aan vanuit een readiness-check.
Een smoke-conversie met een klein, bekend correct document bevestigt het volledige pad van begin tot eind. Dit omvat de multipart-request naar <apiUrl>/forms/libreoffice/convert en de validatie van de response.

Zie ook

/integrations/gotenberg/integration/ — een NextPDF-pipeline via de service aansturen.
/integrations/gotenberg/install/ — installatie van het package en de service.
/integrations/gotenberg/configuration/ — het volledige constructor- en config-contract.
/integrations/gotenberg/overview/ — de conversieflow en het dependency-model.