Gotenberg API-referentie

In een oogopslag

Het Gotenberg-pakket biedt een enkele service-bridge: GotenbergBridge. Die zet een Office-document (docx, xlsx, pptx, odt, ods, odp) om naar Portable Document Format (PDF) door een POST-aanvraag naar een externe Gotenberg-service te sturen. De bridge werkt met de value objects die u doorgeeft of uitleest: GotenbergConfig (de onveranderlijke servicebeschrijving en limieten), OfficeFormat (de enum met ondersteunde formaten), GotenbergConvertPayload (de multipart-aanvraagbody) en GotenbergConvertResult (het geparseerde PDF-antwoord). Een tweede laag, GotenbergSecurityPolicy, GotenbergResponseParser en PinnedCurlTransport, levert de validatie-, parsing- en pinned-transportmechanismen waarop de bridge intern steunt. Gebruik die laag alleen wanneer u eigen transport- of testcode schrijft.

Begin hier: Maak een GotenbergConfig met een service-URL op basis van Hypertext Transfer Protocol Secure (HTTPS) en geef die vervolgens door aan een GotenbergBridge met uw PSR-18-client en PSR-17-factory’s. Roep convertFile() of convertString() aan en lees daarna pdfData uit het geretourneerde GotenbergConvertResult.

Veelvoorkomende taken

Gebruik deze geverifieerde, uitvoerbare fragmenten voor de pakkettaken die u waarschijnlijk het vaakst uitvoert.

Een bestand op schijf naar PDF converteren

Geef de bridge een pad. De bridge detecteert het formaat aan de hand van de extensie.

<?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);

Wat het doet: de bridge valideert de URL, het pad, de grootte en de bestandsnaam; verstuurt een enkele multipart-aanvraag; en schrijft de geretourneerde PDF-bytes naar schijf.

Bytes in het geheugen naar PDF converteren

Gebruik convertString() wanneer u de bytes al hebt. De bestandsnaam bepaalt hoe het formaat wordt gedetecteerd.

<?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.');
}

Wat het doet: de bridge detecteert xlsx aan de hand van de bestandsnaam, converteert de bytes en bevestigt dat het resultaat begint met de %PDF-signatuur voordat u het gebruikt.

De gereedheid van de service controleren voordat u converteert

Laat uw workflow afhangen van isAvailable(). De methode valideert de URL zonder netwerkverkeer en verstuurt vervolgens een enkele HEAD-aanvraag naar /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Wat het doet: de methode retourneert false (gooit nooit een uitzondering) bij een lege URL, een niet-HTTPS-URL of een URL met een privéadres en bij elke netwerkfout, zodat u vroeg kunt afbreken voordat u een conversie verzendt.

Bridge

Deze tabel beschrijft de API-oppervlakte van de bridge. Gebruik deze wanneer u een GotenbergBridge construeert of de conversie- en gereedheidsmethoden ervan aanroept.

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`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-factory’s, optionele logger, optioneel HTML-beleid, optionele response factory.	Gebruikt `DefaultHtmlSecurityPolicy` wanneer u geen beleid opgeeft.	`GotenbergBridge`	Fouten in de containerbedrading.	De response factory schakelt pinned cURL-transport in wanneer pinning vereist is.
`GotenbergBridge::convertFile(string $filePath)`	Bestandssysteempad naar een Office-document.	Gebruikt de bestandsextensie voor formaatdetectie.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` bij een niet-ondersteund formaat.	Lost het werkelijke pad op en controleert leesbaarheid, grootte en bestandsnaam.
`GotenbergBridge::convertString(string $content, string $fileName)`	Onbewerkte bytes en oorspronkelijke bestandsnaam.	Gebruikt de extensie van de bestandsnaam voor formaatdetectie.	`GotenbergConvertResult`	Hetzelfde als `convertFile`.	Gebruik dit wanneer uw applicatie de bestandsbytes al heeft.
`GotenbergBridge::isAvailable()`	geen.	Verstuurt HEAD naar `/health` wanneer de config geldig is.	`bool`	Retourneert `false` bij fouten.	Uitsluitend een gereedheidssignaal.
`GotenbergBridge::getHtmlSecurityPolicy()`	geen.	Retourneert het geconfigureerde beleid uit de parsinglaag.	`HtmlSecurityPolicyInterface`	geen verwacht.	Vult het beveiligingsbeleid op transportniveau aan.

Configuratie en payloads

Deze tabel beschrijft de value objects die u rechtstreeks opbouwt: de servicebeschrijving GotenbergConfig en de aanvraag- en antwoorddragers GotenbergConvertPayload/GotenbergConvertResult. Gebruik ze wanneer u meer controle nodig hebt dan de twee conversie-instappunten bieden.

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	API-URL, time-out, maximale bestandsgrootte, bearer-token, pinsets.	Een lege URL is ongeldig; de standaard maximale grootte is 50 MiB.	`GotenbergConfig`	geen verwacht.	Houd de API-sleutel geheim.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, pin-arrays.	Ontbrekende optionele waarden gebruiken de standaardwaarden van de constructor.	`GotenbergConfig`	geen verwacht.	Stringlijsten negeren niet-stringwaarden.
`GotenbergConfig::isValid()`	geen.	Geldig wanneer de API-URL niet leeg is.	`bool`	geen verwacht.	De veiligheid van de URL wordt gevalideerd vóór elke netwerkbewerking.
`GotenbergConfig::allPublicKeyPins()`	geen.	Combineert primaire en back-uppins.	`list<string>`	geen verwacht.	Een lege lijst schakelt pinning uit.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Bestandsnaam, bytes, formaat, oriëntatievlag, paginabereiken.	Staand; alle pagina’s.	`GotenbergConvertPayload`	geen verwacht.	De payload wordt omgezet naar multipart-formuliergegevens.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Multipart-begrenzing.	Neemt het paginabereikveld alleen op wanneer het niet leeg is.	`string`	geen verwacht.	De bridge genereert de begrenzing.
`GotenbergConvertPayload::contentType(string $boundary)`	Multipart-begrenzing.	Gebruikt `multipart/form-data`.	`string`	geen verwacht.	Gebruik dit als de `Content-Type` van de aanvraag.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Geconverteerde PDF-bytes, bronformaat, optionele weergaveduur.	De weergaveduur is `0.0` wanneer die niet wordt gemeten.	`GotenbergConvertResult`	geen verwacht.	Geretourneerd door `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	geen.	Geldig wanneer de geconverteerde PDF-bytes niet leeg zijn en op PDF-gegevens lijken.	`bool`	geen verwacht.	Controleer dit voordat u het resultaat opslaat of streamt.
`GotenbergConvertResult::size()`	geen.	Telt de geconverteerde PDF-bytes.	`int`	geen verwacht.	Gebruik deze waarde voor quota’s, telemetrie en antwoordlimieten.

Office-formaten

Deze tabel beschrijft de enum OfficeFormat. Gebruik die om een extensie aan een formaat te koppelen, het bijbehorende upload-MIME-type uit te lezen of te controleren welke zes formaten worden ondersteund.

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`OfficeFormat::fromExtension(string $ext)`	Bestandsextensie met of zonder punt ervoor.	Vergelijkt zonder onderscheid tussen hoofdletters en kleine letters.	`OfficeFormat`	`ValueError` bij een niet-ondersteunde extensie.	Ondersteunde waarden: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	geen.	Koppelt de enum-case aan het upload-MIME-type.	`string`	geen verwacht.	Gebruikt in het multipart-bestandsonderdeel.
`OfficeFormat::extension()`	geen.	Retourneert de onderliggende waarde.	`string`	geen verwacht.	Nuttig voor diagnostiek en bestandsnamen.

Beveiliging, parsing en transport

Deze tabel beschrijft de interne mechanismen die de bridge voor u aanstuurt. Gebruik ze alleen wanneer u eigen transport schrijft, een eigen aanroep via Hypertext Transfer Protocol (HTTP) doet waarvoor nog steeds parsing door het pakket nodig is, of het beveiligings- en pinninggedrag op laag niveau inspecteert.

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	Basis-API-URL.	Parseert en valideert de bestemming vóór elke netwerkbewerking.	`array`	`RuntimeException` bij onveilige of ongeldige URL’s.	Houdt eindpuntfouten in de stijl van server-side request forgery (SSRF) buiten de conversiecode.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Host en lijst met vastgezette Internet Protocol-adressen (IP-adressen).	Controleert of de resolutie van het Domain Name System (DNS) nog aan de pinverwachtingen voldoet.	`void`	`RuntimeException` wanneer pins verouderd of ongeldig zijn.	Gebruik het bij pinned deployments en operationele diagnostiek.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Werkelijke grootte en geconfigureerd maximum.	Accepteert bestanden op of onder de geconfigureerde limiet.	`void`	`RuntimeException` wanneer het bestand te groot is.	Dwing dit af voordat de aanvraag wordt opgebouwd.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Oorspronkelijke bestandsnaam.	Weigert onveilige of niet-ondersteunde vormen van bestandsnamen.	`void`	`RuntimeException` bij ongeldige namen.	Voorkomt misvormde multipart-bestandsnamen.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	PSR-7-antwoord en verwacht Office-formaat.	Haalt geconverteerde PDF-bytes uit een geslaagd antwoord.	`GotenbergConvertResult`	`GotenbergConvertException` bij mislukte antwoorden of ongeldige PDF-uitvoer.	Centrale parser voor bestands- en stringconversie.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	PSR-17-factory’s, vastgezette IP-adressen, vastgezette publieke sleutels, time-out.	Geen pins en een time-out van 30 seconden.	`PinnedCurlTransport`	geen verwacht.	Gebruik dit alleen wanneer pinning op cURL-niveau vereist is.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	PSR-7-aanvraag.	Verstuurt via cURL met de geconfigureerde time-out en pinningcontroles.	`ResponseInterface`	`GotenbergConvertException` bij een cURL-/transportfout.	Gebruik het wanneer pinning niet aan een andere HTTP-client kan worden gedelegeerd.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Aanvraag, host en poort.	Bouwt de cURL-optie-array op die `sendRequest()` gebruikt.	`array`	Fouten bij een ongeldige aanvraag of pinconfiguratie.	Diagnostiek op laag niveau en testhaak.

Ontwikkelnotities

Behandel Gotenberg als een externe servicegrens. Stel de time-out, grootte, URL en het pinbeleid bewust in.
convertFile() leest het volledige bestand in het geheugen voordat de aanvraag wordt opgebouwd.
Log metadata zoals de bestandsnaam en de inhoudslengte, niet de bestandsinhoud.