Configurazione di NextPDF Gotenberg

In sintesi

La configurazione si concentra in due punti. Il primo è l’oggetto valore immutabile GotenbergConfig, che descrive il servizio e i relativi limiti. Il secondo è il costruttore di GotenbergBridge, che collega i collaboratori HTTP PSR. Entrambi usano l’iniezione esplicita tramite costruttore. Non esiste stato globale, non vengono lette variabili d’ambiente all’interno del pacchetto e non ci sono endpoint predefiniti nascosti.

L’oggetto di configurazione

GotenbergConfig è un oggetto valore final readonly. È possibile costruirlo direttamente con argomenti denominati oppure crearlo da un array associativo con GotenbergConfig::fromArray().

Campi

Campo	Tipo	Predefinito	Effetto
apiUrl	string	''	URL di base del servizio Gotenberg. È obbligatorio: un valore vuoto rende la configurazione non valida e ogni conversione fallisce immediatamente. Deve essere HTTPS.
timeout	int	30	Limite rigido per il trasferimento, in secondi. Viene applicato dal trasporto cURL con pinning quando tale trasporto è selezionato.
maxFileSize	int	52_428_800	Dimensione massima dell’input in byte (50 MiB). Gli input superiori a questo valore vengono rifiutati prima di qualsiasi richiesta.
apiKey	string	''	Token Bearer. Se non è vuoto, viene inviato come intestazione Authorization: Bearer <token>. È contrassegnato con #[\SensitiveParameter] in modo da essere oscurato negli stack trace.
pinnedPublicKeys	list<string>	[]	Pin SPKI TLS primari nella forma sha256/<base64>. Un valore vuoto disabilita il pinning.
backupPublicKeys	list<string>	[]	Pin SPKI TLS di backup, mantenuti separati in modo che la rotazione possa essere convalidata in modo indipendente.

Costruzione diretta

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

Costruzione da un array

fromArray() accetta chiavi in formato snake_case e ignora qualsiasi valore malformato invece di sollevare un’eccezione. Un api_url non di tipo stringa diventa ''. Un timeout non intero ricade su 30. Un max_file_size non intero ricade sul valore predefinito di 50 MiB. Gli elenchi di pin che non sono array diventano []. Le voci non stringa all’interno degli array di pin vengono scartate.

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

Questo parsing tollerante è intenzionale. Consente di passare direttamente un array di configurazione del framework senza uno strato di pre-convalida, producendo comunque un oggetto ben tipizzato. Non verifica che l’URL sia raggiungibile o che i pin siano corretti. Tali controlli avvengono al momento della conversione.

Validità

isValid() restituisce true solo se apiUrl è una stringa non vuota. Non esegue controlli di rete né sullo schema. Il controllo HTTPS e il filtro degli indirizzi privati avvengono all’interno della policy di sicurezza al momento della conversione. Quando la configurazione non è valida, convertFile() e convertString() sollevano una GotenbergConvertException con il messaggio Invalid Gotenberg configuration: apiUrl is empty. Una configurazione non valida fa anche sì che isAvailable() restituisca false senza alcuna chiamata di rete.

Il costruttore del bridge

GotenbergBridge riceve la configurazione e i collaboratori PSR:

Argomento	Tipo	Obbligatorio	Effetto
config	GotenbergConfig	sì	Il descrittore del servizio e i limiti descritti sopra.
httpClient	Psr\Http\Client\ClientInterface	sì	Il client PSR-18 utilizzato per il probe di integrità e come trasporto di fallback.
requestFactory	Psr\Http\Message\RequestFactoryInterface	sì	Costruisce la richiesta PSR-7.
streamFactory	Psr\Http\Message\StreamFactoryInterface	sì	Costruisce il flusso del corpo della richiesta.
logger	Psr\Log\LoggerInterface|null	no (predefinito null)	Se fornito, registra una voce di livello debug per ogni richiesta di conversione.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	no	Per impostazione predefinita viene usata la policy di sicurezza HTML predefinita del core. Policy a livello di parsing, complementare alla policy a livello di trasporto.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	no (predefinito null)	Necessario per abilitare il trasporto cURL con pinning. Senza di esso il bridge utilizza sempre il client PSR-18 iniettato.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    logger: $psrLogger,
    responseFactory: $psrResponseFactory,
);

Selezione del trasporto

Il bridge supporta due trasporti e ne sceglie uno per ogni richiesta di conversione:

• Trasporto cURL con pinning — utilizzato quando è stato iniettato un responseFactory e c’è qualcosa su cui applicare il pinning (l’URL si è risolto in uno o più IP, oppure sono configurati dei pin SPKI). Questo trasporto vincola l’insieme di indirizzi risolti con CURLOPT_RESOLVE. Applica il pinning SPKI con CURLOPT_PINNEDPUBLICKEY quando sono presenti dei pin. Verifica il peer e l’host (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Applica il timeout configurato e disabilita il follow dei redirect (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Client PSR-18 iniettato — utilizzato in ogni altro caso, anche quando l’URL dell’API è un IP pubblico letterale (nessun DNS su cui applicare il pinning) e non è configurato alcun pin SPKI, oppure quando non è stato fornito alcun responseFactory.

In pratica, per ottenere connessioni resistenti al DNS-rebinding e il pinning TLS, iniettare un responseFactory e configurare i pin. Il probe di integrità usa sempre il client PSR-18 iniettato, indipendentemente dalla selezione del trasporto.

Pinning della chiave pubblica TLS

Il pinning segue il modello di fingerprint SPKI SHA-256. Ogni pin è una stringa della forma sha256/<base64-encoded-spki-hash>. Il trasporto accetta anche la forma nativa di cURL sha256//<base64> e converte in essa la forma con una sola barra. Qualsiasi altro prefisso provoca una InvalidSpkiPinException.

allPublicKeyPins() restituisce l’unione deduplicata di pinnedPublicKeys e backupPublicKeys. Il livello TLS accetta un certificato il cui hash SPKI corrisponde a uno qualsiasi dei membri di tale insieme combinato. Dal punto di vista operativo si dovrebbe configurare almeno un pin di backup, affinché una rotazione pianificata di certificato o chiave non impedisca al bridge di accedere al servizio mentre la nuova chiave si propaga. Mantenere l’elenco di backup separato da quello primario consente di convalidare e ruotare il pin di backup in modo indipendente da quello attivo. Consultare /integrations/gotenberg/security-and-operations/ per la procedura di rotazione.

Opzioni di conversione per richiesta

Oltre al file, il tipo di payload multipart (GotenbergConvertPayload) trasporta due opzioni di conversione Gotenberg facoltative:

• landscape (bool, predefinito false) — inviato come campo del modulo landscape, "true" o "false".
• nativePageRanges (string, predefinito '') — inviato come campo del modulo nativePageRanges solo quando non è vuoto; accetta la sintassi degli intervalli di Gotenberg, come 1-3 o 1,3,5-9.

I punti di ingresso pubblici convertFile() e convertString() costruiscono il payload con i valori predefiniti per questi due campi. I campi fanno parte del contratto del payload e sono coperti dalla suite di test. Esporli nel proprio livello di integrazione se servono output in orizzontale o la selezione delle pagine.

Vedere anche

• /integrations/gotenberg/install/ — installazione e baseline di Gotenberg.
• /integrations/gotenberg/quickstart/ — un esempio end-to-end eseguibile.
• /integrations/gotenberg/production-usage/ — provenienza della configurazione, segreti, timeout, retry.
• /integrations/gotenberg/security-and-operations/ — il modello di sicurezza completo e la rotazione dei pin.
• /integrations/gotenberg/troubleshooting/ — il significato di ciascuna eccezione relativa alla configurazione.