Configuração do NextPDF Gotenberg

Visão geral

A configuração tem duas partes: o value object imutável GotenbergConfig, que descreve o serviço e seus limites, e o construtor GotenbergBridge, que recebe os colaboradores PHP Standard Recommendation (PSR) para o Hypertext Transfer Protocol (HTTP). Você fornece ambos por injeção explícita no construtor. O pacote não tem estado global, não lê variáveis de ambiente e não define nenhum endpoint padrão oculto.

O objeto de configuração

GotenbergConfig é um value object final readonly. Crie-o diretamente com argumentos nomeados ou construa-o a partir de um array associativo com GotenbergConfig::fromArray().

Campos

Campo	Tipo	Padrão	Efeito
apiUrl	string	''	Uniform Resource Locator (URL) base do serviço Gotenberg. Obrigatório: um valor vazio torna a configuração inválida e faz cada conversão falhar imediatamente. Deve usar Hypertext Transfer Protocol Secure (HTTPS).
timeout	int	30	Timeout de transferência rígido em segundos. O transporte fixado em cURL o aplica quando selecionado.
maxFileSize	int	52_428_800	Tamanho máximo de entrada em bytes (50 MiB). Entradas maiores do que isso são rejeitadas antes de qualquer requisição.
apiKey	string	''	Token Bearer. Quando não vazio, é enviado como um cabeçalho Authorization: Bearer <token>. Marcado como #[\SensitiveParameter], de modo que é ocultado em stack traces.
pinnedPublicKeys	list<string>	[]	Pins primários SubjectPublicKeyInfo (SPKI) de Transport Layer Security (TLS) no formato sha256/<base64>. Vazio desabilita o pinning.
backupPublicKeys	list<string>	[]	Pins SPKI de TLS de backup, mantidos separados para que a rotação possa ser validada de forma independente.

Construindo diretamente

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

Construindo a partir de um array

fromArray() aceita chaves em snake_case e ignora valores malformados em vez de lançar exceção. Um api_url que não seja string torna-se ''. Um timeout que não seja int volta para 30. Um max_file_size que não seja int volta para o padrão de 50 MiB. Listas de pins que não sejam arrays tornam-se []. Entradas que não sejam strings dentro dos arrays de pins são descartadas.

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

Esse parsing tolerante é deliberado. Você pode passar diretamente um array de configuração de framework, sem uma camada de pré-validação, e ainda obter um objeto bem tipado. Ele não verifica se a URL é acessível nem se os pins estão corretos. A bridge realiza essas verificações no momento da conversão.

Validade

isValid() retorna true somente quando apiUrl é uma string não vazia. Ela não realiza verificações de rede nem de esquema. A política de segurança cuida do HTTPS e da triagem de endereços privados no momento da conversão. Se a configuração for inválida, convertFile() e convertString() lançam uma GotenbergConvertException com a mensagem Invalid Gotenberg configuration: apiUrl is empty. Uma configuração inválida também faz isAvailable() retornar false sem nenhuma chamada de rede.

O construtor da bridge

GotenbergBridge recebe a configuração mais os colaboradores PSR:

Argumento	Tipo	Obrigatório	Efeito
config	GotenbergConfig	sim	O descritor de serviço e os limites descritos acima.
httpClient	Psr\Http\Client\ClientInterface	sim	O cliente PSR-18 usado para a sonda de integridade e o transporte de fallback.
requestFactory	Psr\Http\Message\RequestFactoryInterface	sim	Constrói a requisição PSR-7.
streamFactory	Psr\Http\Message\StreamFactoryInterface	sim	Constrói o fluxo (stream) do corpo da requisição.
logger	Psr\Log\LoggerInterface|null	não (padrão null)	Quando fornecido, registra uma entrada de nível debug para cada requisição de conversão.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	não	Por padrão, usa a política de segurança de Hypertext Markup Language (HTML) do core. Aplica-se na camada de parsing e complementa a política da camada de transporte.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	não (padrão null)	Necessário para ativar o transporte fixado em cURL. Sem ele, a bridge sempre usa o cliente PSR-18 injetado.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Seleção de transporte

A bridge oferece dois transportes e seleciona um deles para cada requisição de conversão:

• Transporte fixado em cURL — usado quando um responseFactory foi injetado e há algo a fixar (a URL resolveu para um ou mais endereços Internet Protocol (IP), ou pins SPKI estão configurados). Esse transporte vincula o conjunto de endereços resolvidos com CURLOPT_RESOLVE. Ele impõe o pinning SPKI com CURLOPT_PINNEDPUBLICKEY quando há pins presentes. Ele verifica o peer e o host (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Ele aplica o timeout configurado e desabilita o acompanhamento de redirecionamentos (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Cliente PSR-18 injetado — usado em todos os outros casos, inclusive quando a URL da application programming interface (API) é um literal de IP público puro (sem Domain Name System (DNS) a fixar) e nenhum pin SPKI está configurado, ou quando nenhum responseFactory foi fornecido.

Para conexões resistentes a DNS rebinding e com pinning de TLS, injete um responseFactory e configure os pins. A sonda de integridade sempre usa o cliente PSR-18 injetado, independentemente da seleção de transporte.

Pinning de chave pública TLS

O pinning usa o modelo de fingerprint SPKI do Secure Hash Algorithm 256-bit (SHA-256). Cada pin é uma string no formato sha256/<base64-encoded-spki-hash>. O transporte também aceita o formato nativo do cURL sha256//<base64> e converte o formato de barra simples para ele. Qualquer outro prefixo levanta uma InvalidSpkiPinException.

allPublicKeyPins() retorna a união sem duplicatas de pinnedPublicKeys e backupPublicKeys. A camada de TLS aceita um certificado cujo hash SPKI corresponda a qualquer membro desse conjunto combinado. Em operação, configure ao menos um pin de backup para que uma rotação planejada de certificado ou de chave não deixe a bridge sem acesso ao serviço enquanto a nova chave se propaga. Manter a lista de backup separada da lista primária permite validar e rotacionar o pin de backup de forma independente do pin ativo. Consulte /integrations/gotenberg/security-and-operations/ para o procedimento de rotação.

Opções de conversão por requisição

O tipo de payload multipart (GotenbergConvertPayload) carrega o arquivo e mais duas opções opcionais de conversão do Gotenberg:

• landscape (bool, padrão false) — enviado como o campo de formulário landscape com "true" ou "false".
• nativePageRanges (string, padrão '') — enviado como o campo de formulário nativePageRanges somente quando não vazio; aceita a sintaxe de intervalos do Gotenberg, como 1-3 ou 1,3,5-9.

Os pontos de entrada públicos convertFile() e convertString() constroem o payload com os padrões para ambos os campos. Os campos fazem parte do contrato do payload, e a suíte de testes os exercita. Exponha-os a partir da sua camada de integração se você precisar de saída em orientação paisagem ou seleção de páginas.

Veja também

• /integrations/gotenberg/install/ — instalação e baseline do Gotenberg.
• /integrations/gotenberg/quickstart/ — um exemplo executável de ponta a ponta.
• /integrations/gotenberg/production-usage/ — origem da configuração, segredos, timeouts, retentativas.
• /integrations/gotenberg/security-and-operations/ — o modelo de segurança completo e a rotação de pins.
• /integrations/gotenberg/troubleshooting/ — significados das exceções relacionadas à configuração.