NextPDF Gotenberg in productie

In een oogopslag

De bridge voert één synchrone Hypertext Transfer Protocol (HTTP)-roundtrip uit en valideert het resultaat. Hij doet geen herhaalpogingen, gebruikt geen wachtrij en past geen caching of rate-limiting toe. Regel dat gedrag in de applicatie rond de bridge. Deze pagina laat zien wat waar thuishoort en wat de bridge garandeert, zodat je de rest correct kunt inrichten.

Behandel elke conversie als een externe aanroep naar een service die je beheert, maar niet in-process aanstuurt. Houd rekening met de latency en het foutgedrag ervan.

Configuratie en secrets ophalen

GotenbergConfig bevat de Uniform Resource Locator (URL) van de application programming interface (API) en, wanneer authenticatie is ingeschakeld, een bearertoken. Het tokenveld is gemarkeerd met #[\SensitiveParameter], zodat stack traces het maskeren. Je blijft zelf verantwoordelijk voor het veilig ophalen ervan.

• Laad het token bij processtart uit je secret manager of uit een geïnjecteerde omgevingswaarde. Commit het niet en zet het niet in een configuratiebestand dat met de image wordt meegeleverd.
• Bouw de configuratie eenmaal per request-scope of eenmaal per worker op, niet per conversie. De configuratie is immutable en heeft weinig overhead.
• GotenbergConfig::fromArray() accepteert opzettelijk misvormde invoer en vervangt die stilzwijgend door standaardwaarden. Valideer in productie de bronarray voordat je fromArray() aanroept. Een ontbrekende URL verschijnt dan als configuratiefout tijdens het opstarten, niet pas later als per-conversie-exception Invalid Gotenberg configuration: apiUrl is empty.

Time-outs

timeout (seconden, standaard 30) is de harde overdrachtstime-out die door het met cURL gepinde transport wordt toegepast. Office-conversie via LibreOffice is niet onmiddellijk klaar; grote of complexe documenten duren langer. Stem de time-out af op de gemeten conversielatency van je echte documenten, met marge. Houd hem lager dan elke upstream gateway-time-out of de max_execution_time van de PHP-runtime. Dan loopt de bridge als eerste tegen een time-out aan, met een getypeerde exception in plaats van een afgebroken proces.

Als je het geïnjecteerde PHP Standard Recommendation 18 (PSR-18)-clientpad gebruikt (geen responseFactory geïnjecteerd, of een kale Internet Protocol (IP)-URL zonder pins), past de bridge de timeout-waarde niet toe op die client. Configureer de time-out ook op de PSR-18-client, zodat beide transporten begrensd blijven.

Herhaalpogingen

De bridge verstuurt precies één request per aanroep en doet nooit een herhaalpoging. Voeg herhaalpogingen toe in de aanroeper en zorg dat ze veilig zijn:

• Doe alleen een herhaalpoging bij fouten op transportniveau (een GotenbergConvertException waarvan de oorzaak een PSR-18-clientexception is) en idempotente serverfouten (HTTP 502, 503, 504). Doe niet zonder onderscheid een herhaalpoging bij elke GotenbergConvertException. Een response uit de 400-klasse betekent meestal dat de invoer onjuist is, dus een herhaalpoging met dezelfde invoer mislukt op dezelfde manier.
• Gebruik begrensde exponentiële backoff met jitter. Wanneer een conversieservice onder belasting 503 terugstuurt, maakt blijven hameren op de service de storing erger.
• Begrens het totale aantal pogingen en de totale wandkloktijd. Conversie is al traag, dus onbegrensde herhaalpogingen vermenigvuldigen de tail-latency.
• Hervalidatie loopt automatisch: elke herhaalde aanroep voert opnieuw de URL-validatie en de adrescontrole uit, zodat een herhaalpoging de server-side request forgery (SSRF)-beveiliging niet per ongeluk kan omzeilen.

Gelijktijdigheid en capaciteit

Elke conversie houdt aan de Gotenberg-kant één verbinding en één LibreOffice-worker bezet totdat het request klaar is. De bridge zelf is stateless en veilig gelijktijdig vanuit veel workers te gebruiken. Toch heeft de Gotenberg-service een eindige conversiecapaciteit.

• Begrens het aantal lopende conversies aan je kant (met een wachtrij, een semafoor of een worker-pool) tot de capaciteit die Gotenberg aankan. De dimensionering hangt af van je Gotenberg-deployment, niet van dit package; zie /integrations/gotenberg/security-and-operations/.
• De limiet op de invoergrootte (maxFileSize, standaard 50 MiB) is de enige ingebouwde resourcegrens van de bridge. De bridge handhaaft deze in-process voordat het request wordt verstuurd, zodat een te groot bestand nooit servicecapaciteit verbruikt. Verlaag deze limiet tot wat je documenten daadwerkelijk nodig hebben; een kleinere limiet is een goedkopere maatregel tegen denial-of-service dan een grotere.
• Er is geen in-process caching. Als je hetzelfde document herhaaldelijk converteert, cache dan de resulterende Portable Document Format (PDF) in je applicatie, met een content-hash van de invoer als sleutel.

Observability

Injecteer een PHP Standard Recommendation 3 (PSR-3)-logger om één debug-regel per conversierequest te krijgen. De regel bevat de request-URL, de bestandsnaam, het gedetecteerde formaat en de content-lengte van het request, maar geen bestandsinhoud of het bearertoken.

• Zet dat signaal om in een metric: tel conversies op formaat en uitkomst, en leg de wandkloktijd rond elke aanroep van convertFile() / convertString() vast als een latency-histogram. De bridge geeft zelf geen metrics af.
• Het resultaatobject biedt een renderTimeMs-veld. Het is 0.0 tenzij je integratie het meet en instelt; de bridge vult het niet vanuit de Gotenberg-response. Meet de aanroep zelf als je de waarde nodig hebt.
• Log exceptions samen met hun type. Het exceptiontype is het belangrijkste signaal voor wat er is mislukt; zie /integrations/gotenberg/troubleshooting/ voor de catalogus.
• Roep isAvailable() aan vanuit je readiness- of health-endpoint, niet bij elke conversie. isAvailable() stuurt een HEAD naar /health. isAvailable() bij elke conversie uitvoeren verdubbelt zonder voordeel je requesttempo richting de service.

Contract voor foutafhandeling

De bridge meldt fouten als getypeerde exceptions en geeft nooit een gedeeltelijk of ongevalideerd resultaat terug. Hij garandeert het volgende:

• Een status die niet 200 is, een Content-Type zonder application/pdf, of een body die niet begint met %PDF veroorzaakt een GotenbergConvertException. De bridge geeft alleen een resultaatobject terug wanneer alle drie de controles slagen.
• Een PSR-18-clientfout (inclusief een netwerkfout of time-out) wordt verpakt als een GotenbergConvertException, met de oorspronkelijke exception als oorzaak en de code van de client als exceptioncode.
• Validatiefouten (niet-HTTPS-URL, private/reserved-adres, te grote invoer, onveilige bestandsnaam) veroorzaken een RuntimeException vóór elk netwerkverkeer.
• Een niet-herkende bestandsextensie veroorzaakt een ValueError vóór elk netwerkverkeer.

Vang de specifieke typen op. Het voorbeeldprogramma in examples/convert-office-to-pdf.php toont de volledige catch-volgorde. /integrations/gotenberg/troubleshooting/ legt elke trigger uit.

De grens met nabewerking

De bridge produceert een PDF en stopt. Een gangbare productiepipeline is:

1. Converteer het Office-document met deze bridge.
2. Laad de resulterende bytes in een NextPDF-document.
3. Pas nabewerking toe: pagina-assemblage, watermerken, Portable Document Format/Archive (PDF/A)-conversie en digitale handtekeningen.

Stap 3 hoort bij NextPDF, niet bij de bridge. nextpdf/premium biedt ondertekening, PDF/A-profielen en watermerken. Houd conversie en nabewerking als fasen gescheiden, zodat je een conversiefout los van een ondertekeningsfout kunt diagnosticeren.

De ondersteuning voor PDF Advanced Electronic Signatures (PAdES) in de Pro-editie omvat uitsluitend de B-B-baseline. Die biedt geen B-T, B-LT of B-LTA, en die profielen volgen niet impliciet uit conversie van een document via deze bridge. Langetermijnvalidatie is een afzonderlijke editiekwestie en valt buiten de scope van dit package.

Zie ook

• /integrations/gotenberg/configuration/ - regels voor transportselectie en het pinmodel.
• /integrations/gotenberg/security-and-operations/ - de Gotenberg-dependency deployen en hardenen.
• /integrations/gotenberg/troubleshooting/ - de exceptioncatalogus.
• /integrations/gotenberg/integration/ - de geconverteerde PDF koppelen aan een NextPDF-pipeline.