Guia do desenvolvedor para Gotenberg

Visão geral

O pacote Gotenberg encaminha a conversão para Portable Document Format (PDF) a um serviço externo. No código da aplicação, mantenha essa fronteira de serviço explícita: valide a entrada, monte um payload, envie a requisição, analise o resultado e trate falhas do serviço.

Use este guia quando você criar fluxos de conversão de office para PDF, endpoints de upload, verificações de saúde do serviço ou políticas de transporte em torno do nextpdf/gotenberg.

Fronteira de arquitetura

Camada	Pertence a	Responsabilidade	Não coloque aqui
Upload ou origem do documento	Aplicação	Autorize o chamador, valide a origem e escolha a política de conversão.	Decisões sobre endpoint do serviço ou pinning de transporte.
Detecção de formato	`nextpdf/gotenberg`	Mapeie extensões seguras para `OfficeFormat`.	Confiar nos tipos de mídia declarados sem validação pela aplicação.
Ponte	`nextpdf/gotenberg`	Monte a requisição multipart, chame o Gotenberg e analise a resposta em PDF.	Consultas de domínio ou política de armazenamento.
Serviço Gotenberg	Implantação	Converta o documento de office para PDF.	Autorização da aplicação Hypertext Preprocessor (PHP).
Motor principal	`nextpdf/nextpdf`	Importe ou combine dados PDF convertidos quando necessário.	Conversão de office.

Ciclo de vida em tempo de execução

Etapa	Comportamento	Ação do desenvolvedor
Criação da configuração	O endpoint da application programming interface (API), o timeout, o tamanho máximo, a API key e os pins são carregados pela configuração.	Mantenha o endpoint do serviço e o token fora do código-fonte.
Validação de entrada	O caminho do arquivo, o tamanho do arquivo, o nome do arquivo, a extensão e a segurança do Uniform Resource Locator (URL) são verificados.	Rejeite entradas não suportadas antes de despachá-las.
Construção do payload	`GotenbergConvertPayload` monta os dados de formulário multipart.	Preserve o nome do arquivo original apenas quando ele for seguro.
Requisição de serviço	A ponte envia a requisição para `/forms/libreoffice/convert`.	Configure o timeout e a política de transporte.
Análise do resultado	`GotenbergResponseParser::parse()` retorna os bytes do PDF e os metadados.	Trate respostas que não sejam PDF e respostas de erro como falhas na conversão.

Estrutura de aplicação recomendada

Caminho	Propósito
`app/Pdf/Conversion/*`	Wrapper de aplicação em torno do `GotenbergBridge`.
`app/Pdf/Uploads/*`	Validação de upload, armazenamento e política de nomes de arquivo.
`app/Pdf/ConversionPolicy/*`	Política de seleção de tamanho, formato e serviço.
`tests/Pdf/Conversion/*`	Testes de formato, arquivo, serviço e transporte.

Mantenha a validação de arquivo separada da conversão. O serviço de conversão deve receber entradas já autorizadas e, ainda assim, continuar contando com a validação do pacote como defesa em profundidade.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

        if (!$result->isValid()) {
            throw new RuntimeException('The conversion service did not return a valid PDF.');
        }

        return $result->pdfData;
    }
}

Padrões de conversão

Padrão	API	Use quando	Restrição
Converter caminho de arquivo	`GotenbergBridge::convertFile()`	O documento já está armazenado em disco.	O caminho deve ser legível e aprovado pela política.
Converter bytes em memória	`GotenbergBridge::convertString()`	A aplicação já tem bytes de um upload ou de um object store.	O nome do arquivo ainda controla a detecção do formato.
Montar o payload diretamente	`GotenbergConvertPayload`	Você precisa de bytes multipart para testes ou para código de transporte personalizado.	Mantenha a geração do boundary fora da entrada do usuário.
Analisar a resposta diretamente	`GotenbergResponseParser::parse()`	Chamadas Hypertext Transfer Protocol (HTTP) personalizadas ainda precisam da análise feita pelo pacote.	Você deve passar o `OfficeFormat` esperado.

Saúde e prontidão

GotenbergBridge::isAvailable() é um sinal de prontidão, não a sua única proteção em tempo de execução. Um serviço pode passar pela verificação de prontidão e, ainda assim, falhar na próxima conversão.

Verificação	Propósito	Nota operacional
Validade da configuração	Detecte um endpoint da API ausente.	Execute isto durante a inicialização da aplicação ou nas verificações de implantação.
`/health` — disponibilidade	Detecte se o serviço está acessível.	Use isto em dashboards de prontidão.
Conversão de fixture pequena	Detecte comportamento quebrado do LibreOffice ou regressão do serviço.	Execute isto em smoke tests agendados, não em cada requisição.
Monitoramento de timeout	Detecte comportamento lento do serviço.	Acompanhe isto por formato e tamanho de arquivo.

Pontos de extensão

Ponto de extensão	Use para	Restrição
PHP Standard Recommendation (PSR)-18 `ClientInterface`	Comportamento personalizado do cliente HTTP.	Deve seguir a semântica de resposta e exceção da PSR-18.
Factories da PSR-17	Criação de requisição e stream.	Obrigatório para a construção da ponte.
`HtmlSecurityPolicyInterface`	Política na camada de análise para entradas em Hypertext Markup Language (HTML).	Complementa a política de segurança do Gotenberg.
`ResponseFactoryInterface`	Construção de resposta do transporte cURL com pinning.	Obrigatório apenas quando você usa o caminho de transporte do pacote.
`GotenbergSecurityPolicy`	Validação de URL, tamanho de arquivo, nome de arquivo e pin.	Mantenha a autorização da aplicação fora dessa camada.

Fluxo de desenvolvimento

Comece com convertString() nos testes para manter as fixtures explícitas.
Adicione convertFile() apenas depois que os caminhos do sistema de arquivos estiverem sob controle.
Mantenha o tamanho máximo de arquivo abaixo dos limites do serviço e da infraestrutura.
Use isAvailable() para sinais de prontidão, não como substituto do tratamento de erros.
Registre nome do arquivo, formato, tamanho, status e duração. Não registre os bytes do documento.
Adicione testes de timeout e de modos de falha antes de expor endpoints de upload.

Tratamento de falhas

Falha	Onde deve ser tratada	Resposta recomendada
Extensão não suportada	Detecção de formato.	Rejeite antes de despachar para o serviço.
Nome de arquivo inseguro	Política de segurança.	Rejeite-o e normalize a política de nomes de upload.
Arquivo grande demais	Política de upload e validação do pacote.	Rejeite antes de ler ou enviar payloads grandes.
Gotenberg indisponível	Fronteira da ponte.	Retorne um erro de aplicação que permita nova tentativa quando apropriado.
Resposta que não é PDF	Analisador de resposta.	Trate-a como uma falha de conversão e capture o status do serviço.
Falha de validação de pin ou URL	Política de transporte.	Falhe de forma fechada e alerte os operadores.

Padrões seguros

Aspecto	Padrão	Quando substituir
Timeout	`30` segundos.	Aumente apenas depois de medir a latência real do serviço.
Tamanho máximo de arquivo	`52,428,800` bytes.	Reduza para endpoints públicos ou multi-tenant.
API key	Vazia.	Defina para implantações privadas do Gotenberg.
Formatos suportados	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	Adicione formatos apenas quando `OfficeFormat` e o analisador os suportarem.
Conjuntos de pins	Vazio.	Adicione pins com pins de backup e um procedimento de rotação.

Checklist de testes

Os testes de formato cobrem extensões suportadas e não suportadas.
Os testes de arquivo cobrem arquivos ausentes, arquivos ilegíveis, arquivos grandes demais e nomes de arquivo inseguros.
Os testes de serviço cobrem respostas que não são 2xx, corpos de resposta inválidos e exceções de transporte.
Os testes de segurança cobrem URLs de serviço privadas ou inválidas quando a política as proíbe.
Os testes de timeout asseguram que o timeout configurado seja passado para o transporte.
Os testes de fixture mantêm os documentos de exemplo pequenos e sem dados sensíveis.