Gotenberg-ontwikkelaarsgids

In het kort

Het Gotenberg-pakket stuurt conversie naar Portable Document Format (PDF) door naar een externe service. Houd die servicegrens expliciet in applicatiecode: valideer de invoer, bouw een payload, verstuur het verzoek, verwerk het resultaat en handel servicefouten af.

Gebruik deze gids wanneer je workflows bouwt voor office-naar-PDF-conversie, upload-endpoints, servicegezondheidscontroles of transportbeleid rond nextpdf/gotenberg.

Architectuurgrens

Laag	Eigendom van	Verantwoordelijkheid	Plaats hier niet
Upload- of documentbron	Applicatie	Autoriseer de aanroeper, valideer de bron en kies het conversiebeleid.	Beslissingen over service-endpoints of transport-pinning.
Formaatdetectie	`nextpdf/gotenberg`	Koppel veilige extensies aan `OfficeFormat`.	Vertrouwen op gedeclareerde mediatypen zonder validatie in de applicatie.
Bridge	`nextpdf/gotenberg`	Bouw het multipart-verzoek, roep Gotenberg aan en verwerk het PDF-antwoord.	Domeinquery’s of opslagbeleid.
Gotenberg-service	Implementatie	Converteer het office-document naar PDF.	Autorisatie in de Hypertext Preprocessor (PHP)-applicatie.
Core-engine	`nextpdf/nextpdf`	Importeer of combineer geconverteerde PDF-gegevens wanneer dat nodig is.	Office-conversie.

Runtime-levenscyclus

Fase	Gedrag	Actie van de ontwikkelaar
Configuratie aanmaken	Het application programming interface (API)-endpoint, de timeout, de maximale grootte, de API-sleutel en de pins worden uit de configuratie geladen.	Houd het service-endpoint en het token buiten de broncode.
Invoervalidatie	Het bestandspad, de bestandsgrootte, de bestandsnaam, de extensie en de veiligheid van de Uniform Resource Locator (URL) worden gecontroleerd.	Wijs niet-ondersteunde invoer af voordat je die verstuurt.
Payload opbouwen	`GotenbergConvertPayload` bouwt multipart-formuliergegevens op.	Bewaar de oorspronkelijke bestandsnaam alleen wanneer die veilig is.
Serviceverzoek	De bridge stuurt het verzoek naar `/forms/libreoffice/convert`.	Configureer de timeout en het transportbeleid.
Resultaat verwerken	`GotenbergResponseParser::parse()` retourneert PDF-bytes en metadata.	Behandel niet-PDF-antwoorden en foutantwoorden als conversiefouten.

Aanbevolen applicatiestructuur

Pad	Doel
`app/Pdf/Conversion/*`	Applicatiewrapper rond `GotenbergBridge`.
`app/Pdf/Uploads/*`	Uploadvalidatie, opslag en bestandsnaambeleid.
`app/Pdf/ConversionPolicy/*`	Beleid voor grootte, formaat en serviceselectie.
`tests/Pdf/Conversion/*`	Tests voor formaat, bestand, service en transport.

Houd bestandsvalidatie gescheiden van conversie. Je conversieservice hoort al geautoriseerde invoer te ontvangen en moet tegelijk op de validatie van het pakket blijven vertrouwen als verdediging in de diepte.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

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

        return $result->pdfData;
    }
}

Conversiepatronen

Patroon	API	Gebruik wanneer	Beperking
Bestandspad converteren	`GotenbergBridge::convertFile()`	Het document staat al op schijf.	Het pad moet leesbaar zijn en door beleid zijn goedgekeurd.
In-memory bytes converteren	`GotenbergBridge::convertString()`	Je applicatie heeft al bytes uit een upload of een object store.	De bestandsnaam stuurt nog steeds de formaatdetectie aan.
Payload rechtstreeks bouwen	`GotenbergConvertPayload`	Je hebt multipart-bytes nodig voor tests of voor eigen transportcode.	Houd het genereren van de boundary buiten de gebruikersinvoer.
Antwoord rechtstreeks verwerken	`GotenbergResponseParser::parse()`	Eigen Hypertext Transfer Protocol (HTTP)-aanroepen hebben nog steeds de verwerking van het pakket nodig.	Je moet het verwachte `OfficeFormat` doorgeven.

Gezondheid en gereedheid

GotenbergBridge::isAvailable() is een gereedheidssignaal, niet je enige runtime-waarborg. Een service kan de gereedheidscontrole doorstaan en toch bij de volgende conversie mislukken.

Controle	Doel	Operationele opmerking
Configuratiegeldigheid	Detecteer een ontbrekend API-endpoint.	Voer dit uit tijdens het opstarten van de app of bij implementatiecontroles.
Beschikbaarheid van `/health`	Detecteer of de service bereikbaar is.	Gebruik dit voor gereedheidsdashboards.
Conversie van een kleine fixture	Detecteer kapot LibreOffice-gedrag of een serviceregressie.	Voer dit uit in geplande smoke-tests, niet bij elk verzoek.
Timeout-monitoring	Detecteer traag servicegedrag.	Monitor dit per formaat en bestandsgrootte.

Uitbreidingspunten

Uitbreidingspunt	Gebruik het voor	Beperking
PHP Standard Recommendation (PSR)-18 `ClientInterface`	Aangepast gedrag van de HTTP-client.	Moet de respons- en exception-semantiek van PSR-18 volgen.
PSR-17-factory’s	Aanmaken van verzoek en stream.	Vereist om de bridge te construeren.
`HtmlSecurityPolicyInterface`	Beleid op parse-niveau voor invoer in Hypertext Markup Language (HTML).	Vormt een aanvulling op het beveiligingsbeleid van Gotenberg.
`ResponseFactoryInterface`	Constructie van het antwoord voor het vastgepinde cURL-transport.	Alleen vereist wanneer je het transportpad van het pakket gebruikt.
`GotenbergSecurityPolicy`	Validatie van URL, bestandsgrootte, bestandsnaam en pin.	Houd applicatieautorisatie buiten deze laag.

Ontwikkelworkflow

Begin met convertString() in tests om fixtures expliciet te houden.
Voeg convertFile() pas toe wanneer de bestandssysteempaden onder controle zijn.
Houd de maximale bestandsgrootte onder de limieten van de service en de infrastructuur.
Gebruik isAvailable() voor gereedheidssignalen, niet als vervanging voor foutafhandeling.
Log de bestandsnaam, het formaat, de grootte, de status en de duur. Log geen documentbytes.
Voeg tests voor timeouts en faalmodi toe voordat je upload-endpoints blootstelt.

Foutafhandeling

Fout	Waar deze moet worden afgehandeld	Aanbevolen respons
Niet-ondersteunde extensie	Formaatdetectie.	Wijs af voordat je naar de service verstuurt.
Onveilige bestandsnaam	Beveiligingsbeleid.	Wijs deze af en normaliseer het naamgevingsbeleid voor uploads.
Te groot bestand	Uploadbeleid en validatie van het pakket.	Wijs af voordat je grote payloads inleest of verstuurt.
Gotenberg niet beschikbaar	Bridge-grens.	Retourneer waar passend een opnieuw te proberen applicatiefout.
Niet-PDF-antwoord	Antwoordverwerker.	Behandel dit als een conversiefout en leg de servicestatus vast.
Validatiefout voor pin of URL	Transportbeleid.	Faal gesloten en waarschuw de operators.

Veilige standaardwaarden

Aandachtspunt	Standaard	Wanneer overschrijven
Timeout	`30` seconden.	Verhoog dit alleen nadat je de werkelijke servicelatentie hebt gemeten.
Maximale bestandsgrootte	`52,428,800` bytes.	Verlaag dit voor publieke of multi-tenant-endpoints.
API-sleutel	Leeg.	Stel dit in voor private Gotenberg-implementaties.
Ondersteunde formaten	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	Voeg formaten alleen toe wanneer `OfficeFormat` en de verwerker ze ondersteunen.
Pin-sets	Leeg.	Voeg pins toe met back-uppins en een rotatieprocedure.

Testchecklist

Formaattests dekken ondersteunde en niet-ondersteunde extensies.
Bestandstests dekken ontbrekende bestanden, onleesbare bestanden, te grote bestanden en onveilige bestandsnamen.
Servicetests dekken niet-2xx-antwoorden, ongeldige antwoordbodies en transport-exceptions.
Beveiligingstests dekken private of ongeldige service-URL’s wanneer het beleid die verbiedt.
Timeout-tests stellen vast dat de geconfigureerde timeout aan het transport wordt doorgegeven.
Fixture-tests houden voorbeelddocumenten klein en niet-gevoelig.