Referência da API do Gotenberg

Visão geral

O pacote Gotenberg expõe uma ponte de serviço, GotenbergBridge. Ela converte um documento Office (docx, xlsx, pptx, odt, ods, odp) para Portable Document Format (PDF) ao enviar uma requisição POST para um serviço Gotenberg externo. A ponte trabalha com os objetos de valor que você passa ou lê: GotenbergConfig (o descritor de serviço imutável e os limites), OfficeFormat (o enum de formatos suportados), GotenbergConvertPayload (o corpo multipart da requisição) e GotenbergConvertResult (a resposta PDF já analisada). Uma segunda camada, GotenbergSecurityPolicy, GotenbergResponseParser e PinnedCurlTransport, fornece a infraestrutura de validação, análise e transporte com pinning que a ponte aciona internamente. Use essa camada apenas quando você escrever transporte personalizado ou código de teste.

Comece por aqui: Crie um GotenbergConfig com a URL de serviço Hypertext Transfer Protocol Secure (HTTPS) e passe-o para uma GotenbergBridge com o cliente PSR-18 e as factories PSR-17. Chame convertFile() ou convertString() e depois leia pdfData no GotenbergConvertResult.

Tarefas comuns

Use estes trechos verificados e executáveis para as tarefas do pacote que você provavelmente vai realizar com mais frequência.

Converter um arquivo em disco para PDF

Aponte a ponte para um caminho. Ela detecta o formato pela extensão.

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

O que ela faz: valida a URL, o caminho, o tamanho e o nome do arquivo; envia uma requisição multipart; e grava em disco os bytes do PDF retornado.

Converter bytes em memória para PDF

Use convertString() quando você já tiver os bytes. O nome do arquivo orienta a detecção de formato.

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

O que ela faz: detecta xlsx pelo nome do arquivo, converte os bytes e confirma que o resultado começa com a assinatura %PDF antes de você usá-lo.

Verificar a disponibilidade do serviço antes de converter

Condicione o trabalho a isAvailable(). Ela valida a URL sem tráfego de rede e depois envia uma requisição HEAD para /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

O que ela faz: retorna false (nunca lança exceção) para uma URL vazia, sem HTTPS ou com endereço privado, e para qualquer erro de rede, para que você possa falhar rapidamente antes de disparar uma conversão.

Ponte

Esta tabela cobre a superfície da ponte. Use-a quando você construir GotenbergBridge ou chamar seus métodos de conversão e disponibilidade.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Config, cliente PSR-18, factories PSR-17, logger opcional, política HTML opcional, response factory opcional.	Usa `DefaultHtmlSecurityPolicy` quando você não fornece uma política.	`GotenbergBridge`	Erros de wiring do container.	A response factory habilita o transporte cURL com pinning quando o pinning é obrigatório.
`GotenbergBridge::convertFile(string $filePath)`	Caminho no sistema de arquivos para um documento Office.	Usa a extensão do arquivo para detectar o formato.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` para formato não suportado.	Resolve o caminho real e verifica a legibilidade, o tamanho e o nome do arquivo.
`GotenbergBridge::convertString(string $content, string $fileName)`	Bytes brutos e nome de arquivo original.	Usa a extensão do nome do arquivo para detectar o formato.	`GotenbergConvertResult`	Igual a `convertFile`.	Use quando a aplicação já tiver os bytes do arquivo.
`GotenbergBridge::isAvailable()`	nenhum.	Envia HEAD para `/health` quando a configuração é válida.	`bool`	Retorna `false` em caso de erro.	Apenas sinaliza disponibilidade.
`GotenbergBridge::getHtmlSecurityPolicy()`	nenhum.	Retorna a política configurada da camada de análise.	`HtmlSecurityPolicyInterface`	nenhum esperado.	Complementa a política de segurança no nível de transporte.

Configuração e payloads

Esta tabela cobre os objetos de valor que você constrói diretamente: o descritor de serviço GotenbergConfig e os transportadores de requisição e resposta GotenbergConvertPayload/GotenbergConvertResult. Use-os quando você precisar de um controle mais fino do que os dois pontos de entrada de conversão oferecem.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	URL da API, timeout, tamanho máximo do arquivo, bearer token, conjuntos de pins.	Uma URL vazia é inválida; o tamanho máximo padrão é 50 MiB.	`GotenbergConfig`	nenhum esperado.	Mantenha a chave de API em segredo.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, arrays de pins.	Valores opcionais ausentes usam os padrões do construtor.	`GotenbergConfig`	nenhum esperado.	Listas de strings ignoram valores que não são strings.
`GotenbergConfig::isValid()`	nenhum.	Válido quando a URL da API não está vazia.	`bool`	nenhum esperado.	A segurança da URL é validada antes de qualquer operação de rede.
`GotenbergConfig::allPublicKeyPins()`	nenhum.	Combina os pins primários e de backup.	`list<string>`	nenhum esperado.	Uma lista vazia desativa o pinning.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Nome do arquivo, bytes, formato, flag de orientação, intervalos de páginas.	Retrato; todas as páginas.	`GotenbergConvertPayload`	nenhum esperado.	O payload é convertido em dados de formulário multipart.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Boundary multipart.	Inclui o campo de intervalo de páginas apenas quando ele não está vazio.	`string`	nenhum esperado.	A ponte gera o boundary.
`GotenbergConvertPayload::contentType(string $boundary)`	Boundary multipart.	Usa `multipart/form-data`.	`string`	nenhum esperado.	Anexe como o `Content-Type`.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Bytes do PDF convertido, formato de origem, duração de renderização opcional.	A duração de renderização é `0.0` quando ela não é medida.	`GotenbergConvertResult`	nenhum esperado.	Retornado por `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	nenhum.	Válido quando os bytes do PDF convertido não estão vazios e parecem dados de PDF.	`bool`	nenhum esperado.	Verifique antes de persistir ou transmitir o resultado.
`GotenbergConvertResult::size()`	nenhum.	Conta os bytes do PDF convertido.	`int`	nenhum esperado.	Use-o para cotas, telemetria e limites de resposta.

Formatos Office

Esta tabela cobre o enum OfficeFormat. Use-o para mapear uma extensão para um formato, ler o tipo MIME de upload ou verificar quais seis formatos são suportados.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`OfficeFormat::fromExtension(string $ext)`	Extensão de arquivo com ou sem ponto inicial.	Faz a correspondência sem diferenciar maiúsculas de minúsculas.	`OfficeFormat`	`ValueError` para extensão não suportada.	Valores suportados: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	nenhum.	Mapeia o caso do enum para o tipo MIME de upload.	`string`	nenhum esperado.	Usado na parte de arquivo do multipart.
`OfficeFormat::extension()`	nenhum.	Retorna o valor associado.	`string`	nenhum esperado.	Útil em diagnósticos e nomes de arquivos.

Segurança, análise e transporte

Esta tabela cobre a infraestrutura interna que a ponte aciona para você. Use-a apenas quando você escrever transporte personalizado, fizer uma chamada Hypertext Transfer Protocol (HTTP) personalizada que ainda precise da análise do pacote ou inspecionar o comportamento de segurança e pinning de baixo nível.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	URL base da API.	Analisa e valida o destino antes de qualquer operação de rede.	`array`	`RuntimeException` para URLs inseguras ou inválidas.	Mantém erros de endpoint do tipo server-side request forgery (SSRF) fora do código de conversão.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Host e lista de Internet Protocol (IP) com pinning.	Verifica as expectativas de pin de Domain Name System (DNS).	`void`	`RuntimeException` quando os pins estão obsoletos ou inválidos.	Use-a em implantações com pinning e diagnósticos operacionais.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Tamanho real e máximo configurado.	Aceita arquivos iguais ou abaixo do limite configurado.	`void`	`RuntimeException` quando o arquivo é grande demais.	Aplique antes da construção da requisição.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Nome de arquivo original.	Rejeita formas de nome de arquivo inseguras ou não suportadas.	`void`	`RuntimeException` para nomes inválidos.	Evita nomes de arquivo multipart malformados.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	Resposta PSR-7 e formato Office esperado.	Extrai os bytes do PDF convertido de uma resposta bem-sucedida.	`GotenbergConvertResult`	`GotenbergConvertException` para respostas com falha ou saída PDF inválida.	Analisador central para conversões de arquivo e de string.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	Factories PSR-17, IPs com pinning, chaves públicas com pinning, timeout.	Sem pins e timeout de 30 segundos.	`PinnedCurlTransport`	nenhum esperado.	Use apenas quando o pinning em nível de cURL for obrigatório.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	Requisição PSR-7.	Envia via cURL com o timeout configurado e os controles de pinning.	`ResponseInterface`	`GotenbergConvertException` em caso de falha de cURL/transporte.	Use-o quando o pinning não puder ser delegado a outro cliente HTTP.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Requisição, host e porta.	Constrói o array de opções de cURL que `sendRequest()` usa.	`array`	Erros de requisição inválida ou de configuração de pin.	Hook de diagnóstico e teste de baixo nível.

Notas de desenvolvimento

Trate o Gotenberg como um limite de serviço externo. Defina deliberadamente o timeout, o tamanho, a URL e a política de pin.
convertFile() lê o arquivo inteiro para a memória antes de construir a requisição.
Registre metadados como nome do arquivo e tamanho do conteúdo, não o conteúdo do arquivo.