NextPDF Gotenberg configureren

In het kort

De configuratie bestaat uit twee delen: het onveranderlijke value-object GotenbergConfig, dat de service en de bijbehorende limieten beschrijft, en de constructor van GotenbergBridge, die de PHP Standard Recommendation (PSR)-collaborators voor het Hypertext Transfer Protocol (HTTP) ontvangt. Je geeft beide door via expliciete constructor-injectie. Het pakket heeft geen globale status, leest geen omgevingsvariabelen en definieert geen verborgen standaardendpoint.

Het configuratieobject

GotenbergConfig is een final readonly value-object. Maak het rechtstreeks aan met named arguments, of bouw het op uit een associatieve array met GotenbergConfig::fromArray().

Velden

Veld	Type	Standaard	Effect
apiUrl	string	''	Basis-Uniform Resource Locator (URL) voor de Gotenberg-service. Vereist: een lege waarde maakt de config ongeldig en elke conversie mislukt direct. Moet Hypertext Transfer Protocol Secure (HTTPS) gebruiken.
timeout	int	30	Strikte overdrachtstime-out in seconden. Het cURL-transport met pinning past die toe wanneer het wordt geselecteerd.
maxFileSize	int	52_428_800	Maximale invoergrootte in bytes (50 MiB). Grotere invoer wordt geweigerd voordat er een verzoek wordt gedaan.
apiKey	string	''	Bearer-token. Als dit niet leeg is, wordt het verzonden als een Authorization: Bearer <token>-header. Is gemarkeerd als #[\SensitiveParameter], zodat het in stacktraces wordt geredigeerd.
pinnedPublicKeys	list<string>	[]	Primaire Transport Layer Security (TLS) SubjectPublicKeyInfo (SPKI)-pins in de vorm sha256/<base64>. Een lege lijst schakelt pinning uit.
backupPublicKeys	list<string>	[]	Back-up-TLS-SPKI-pins, apart gehouden zodat rotatie onafhankelijk kan worden gevalideerd.

Rechtstreeks construeren

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

Construeren vanuit een array

fromArray() accepteert snake_case-sleutels en negeert misvormde waarden in plaats van een exception te werpen. Een niet-string api_url wordt ''. Een niet-int timeout valt terug op 30. Een niet-int max_file_size valt terug op de standaard van 50 MiB. Niet-array pinlijsten worden []. Niet-string-items binnen de pin-arrays worden verwijderd.

<?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='],
]);

Deze tolerante parsing is bewust gekozen. Je kunt een framework-configuratiearray rechtstreeks doorgeven zonder voorvalidatielaag en krijgt toch een goed getypeerd object. Het verifieert niet of de URL bereikbaar is of dat de pins kloppen. De bridge voert die controles uit tijdens de conversie.

Geldigheid

isValid() geeft alleen true terug wanneer apiUrl een niet-lege string is. Het voert geen netwerk- of schemacontroles uit. Het beveiligingsbeleid handelt HTTPS en het screenen van privéadressen af tijdens de conversie. Als de config ongeldig is, werpen convertFile() en convertString() een GotenbergConvertException met het bericht Invalid Gotenberg configuration: apiUrl is empty. Een ongeldige config zorgt er ook voor dat isAvailable() false teruggeeft zonder netwerkaanroep.

De constructor van de bridge

GotenbergBridge ontvangt de configuratie en de PSR-collaborators:

Argument	Type	Vereist	Effect
config	GotenbergConfig	ja	De service-descriptor en de hierboven beschreven limieten.
httpClient	Psr\Http\Client\ClientInterface	ja	De PSR-18-client die wordt gebruikt voor de health probe en het fallbacktransport.
requestFactory	Psr\Http\Message\RequestFactoryInterface	ja	Bouwt het PSR-7-verzoek op.
streamFactory	Psr\Http\Message\StreamFactoryInterface	ja	Bouwt de stream voor de verzoeksbody op.
logger	Psr\Log\LoggerInterface|null	nee (standaard null)	Als deze is aangeleverd, wordt per conversieverzoek één vermelding op debug-niveau gelogd.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	nee	Valt standaard terug op het Hypertext Markup Language (HTML)-beveiligingsbeleid van core. Wordt toegepast op de parselaag en vult het beleid op transportniveau aan.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	nee (standaard null)	Vereist om het cURL-transport met pinning te activeren. Zonder dit gebruikt de bridge altijd de geïnjecteerde 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,
);

Transportselectie

De bridge ondersteunt twee transporten en kiest er per conversieverzoek één:

• cURL-transport met pinning — gebruikt wanneer er een responseFactory is geïnjecteerd en er iets is om te pinnen (de URL is herleid tot een of meer Internet Protocol (IP)-adressen, of er zijn SPKI-pins geconfigureerd). Dit transport bindt de herleide adressen met CURLOPT_RESOLVE. Het dwingt SPKI-pinning af met CURLOPT_PINNEDPUBLICKEY wanneer er pins aanwezig zijn. Het verifieert de peer en de host (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Het past de geconfigureerde time-out toe en schakelt het volgen van redirects uit (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Geïnjecteerde PSR-18-client — gebruikt in elk ander geval, ook wanneer de application programming interface (API)-URL een kale publieke IP-literal is (geen Domain Name System (DNS) om te pinnen) en er geen SPKI-pins zijn geconfigureerd, of wanneer er geen responseFactory is aangeleverd.

Injecteer voor verbindingen die bestand zijn tegen DNS-rebinding en voor TLS-pinning een responseFactory en configureer pins. De health probe gebruikt altijd de geïnjecteerde PSR-18-client, ongeacht welk transport wordt gekozen.

TLS-pinning van publieke sleutels

Pinning gebruikt het SPKI-fingerprintmodel met Secure Hash Algorithm 256-bit (SHA-256). Elke pin is een string in de vorm sha256/<base64-encoded-spki-hash>. Het transport accepteert ook de native cURL-vorm sha256//<base64> en zet de vorm met één schuine streep daarnaar om. Elk ander prefix veroorzaakt een InvalidSpkiPinException.

allPublicKeyPins() geeft de ontdubbelde vereniging van pinnedPublicKeys en backupPublicKeys terug. De TLS-laag accepteert een certificaat waarvan de SPKI-hash overeenkomt met een willekeurig lid van die gecombineerde set. Configureer voor operations ten minste één back-up-pin, zodat een geplande certificaat- of sleutelrotatie de bridge niet buitensluit van de service terwijl de nieuwe sleutel zich verspreidt. Door de back-uplijst gescheiden te houden van de primaire lijst kun je de back-up-pin onafhankelijk van de actieve pin valideren en roteren. Zie /integrations/gotenberg/security-and-operations/ voor de rotatieprocedure.

Conversieopties per verzoek

Het multipart-payloadtype (GotenbergConvertPayload) bevat het bestand en twee optionele Gotenberg-conversieopties:

• landscape (bool, standaard false) — verzonden als het formulierveld landscape met "true" of "false".
• nativePageRanges (string, standaard '') — alleen verzonden als formulierveld nativePageRanges wanneer het niet leeg is; accepteert de bereiksyntaxis van Gotenberg, zoals 1-3 of 1,3,5-9.

De publieke entry points convertFile() en convertString() bouwen de payload op met de standaardwaarden voor beide velden. De velden maken deel uit van het payload-contract en de testsuite test ze. Maak ze beschikbaar vanuit je integratielaag als je liggende uitvoer of paginaselectie nodig hebt.

Zie ook

• /integrations/gotenberg/install/ — installatie en de Gotenberg-baseline.
• /integrations/gotenberg/quickstart/ — een uitvoerbaar end-to-end-voorbeeld.
• /integrations/gotenberg/production-usage/ — config-sourcing, secrets, time-outs, retries.
• /integrations/gotenberg/security-and-operations/ — het volledige beveiligingsmodel en pin-rotatie.
• /integrations/gotenberg/troubleshooting/ — de betekenis van configuratiegerelateerde exceptions.