Instalar o NextPDF Gotenberg

Visão geral

A instalação da ponte envolve duas partes: o pacote PHP e as dependências HTTP de PHP Standard Recommendation (PSR), que você instala com o Composer, e o serviço Gotenberg chamado pelo pacote. A ponte converte arquivos enviando o trabalho para esse serviço; portanto, não consegue realizar conversões enquanto uma instância do Gotenberg não estiver acessível.

Conclua as duas partes antes de implementar o código de conversão.

Requisitos

Requisito	Restrição	Por quê
PHP	>=8.4 <9.0	Declarado pelo pacote no composer.json.
NextPDF core	^3.0	Declarado como dependência direta no composer.json.
Cliente HTTP PSR-18	^1.0	A ponte envia requisições por meio de uma Psr\Http\Client\ClientInterface injetada.
Fábricas HTTP PSR-17	^1.1	A ponte constrói requisições e streams com fábricas PSR-17 injetadas.
Logger PSR-3	^3.0 (opcional)	Você pode injetar um logger para registrar depuração no nível da requisição.
Serviço Gotenberg	Acessível por HTTPS	O serviço externo realiza a conversão; este pacote não.

A ponte não inclui um cliente PSR-18 nem fábricas PSR-17. Escolha as implementações que se encaixem na sua aplicação. Por exemplo, combine um cliente baseado em Guzzle com as fábricas PSR-17 correspondentes ou use o cliente HTTP do Symfony com o nyholm/psr7. Qualquer implementação em conformidade com os contratos PSR pertinentes funciona, porque a ponte depende de interfaces, não de uma biblioteca específica.

Etapa 1 — instalar o pacote

Adicione o pacote com o Composer:

composer require nextpdf/gotenberg

O Composer resolve o nextpdf/core ^3.0 e os contratos HTTP PSR: psr/http-client, psr/http-factory e psr/log. Ele não instala um cliente HTTP concreto.

Etapa 2 — instalar um cliente PSR-18 e fábricas PSR-17

Instale um cliente PSR-18 e o conjunto correspondente de fábricas PSR-17. Com o Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Ou com o cliente HTTP do Symfony e o Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

Passe essas implementações ao construtor da ponte. A ponte nunca instancia um cliente HTTP por conta própria. Você escolhe a implementação ao montar a ponte. Consulte /integrations/gotenberg/configuration/ para conhecer a estrutura do construtor e /integrations/gotenberg/quickstart/ para ver um exemplo completo de montagem.

Etapa 3 — colocar um serviço Gotenberg em funcionamento

A ponte chama a rota de conversão do LibreOffice do Gotenberg; portanto, execute uma instância do Gotenberg que a ponte consiga acessar. O projeto upstream publica uma imagem de contêiner. Para desenvolvimento local, use:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Isso expõe o Gotenberg na porta 3000 em HTTP simples. Use essa configuração apenas para desenvolvimento local. A ponte exige HTTPS para a URL configurada da application programming interface (API) e rejeita http:// simples antes de enviar qualquer requisição. Para qualquer uso além de um experimento local, coloque o Gotenberg atrás de um proxy reverso ou service mesh que faça a terminação de Transport Layer Security (TLS) e, em seguida, aponte a ponte para o endpoint HTTPS. /integrations/gotenberg/security-and-operations/ cobre a estrutura de implantação em produção, a exposição de rede e a autenticação.

A tag de imagem mostrada aqui (gotenberg/gotenberg:8) é a linha upstream principal (major) do Gotenberg. O README e a base de integração deste projeto referenciam essa linha. Em produção, fixe uma tag de patch específica em vez de acompanhar uma tag major móvel. Confira também os caminhos das rotas (/forms/libreoffice/convert, /health) em relação à versão do Gotenberg que você implanta. A ponte pressupõe esses dois caminhos e não assume mais nada sobre o serviço.

Etapa 4 — verificar a montagem

Neste ponto, o pacote e um cliente HTTP estão instalados, e o Gotenberg está acessível por HTTPS. Antes de executar uma conversão real, confirme que a ponte consegue alcançar o serviço com a sonda de integridade integrada:

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(apiUrl: 'https://gotenberg.example.com');

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

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() valida primeiro a URL configurada. O método retorna false para uma URL vazia, uma URL não HTTPS ou uma URL apontando para endereço privado sem enviar tráfego de rede. Depois, envia uma requisição HEAD para <apiUrl>/health e considera o serviço disponível quando o status é inferior a 500. Se ocorrer um erro de rede, a ponte o captura e considera o serviço indisponível em vez de lançar uma exceção.

Nota sobre versão

Esta documentação descreve o pacote na linha ^3.0. Essa linha corresponde ao requisito do composer.json e à matriz de suporte do SECURITY.md, na qual a 3.x é suportada e a 2.x não. Referências antigas a 0.x nas páginas de esqueleto do repositório são anteriores à linha 3.0. A restrição do composer.json prevalece sobre elas.

Veja também

• /integrations/gotenberg/overview/ — o que a ponte faz e quais formatos ela converte.
• /integrations/gotenberg/configuration/ — cada argumento do construtor e campo de configuração.
• /integrations/gotenberg/quickstart/ — uma primeira conversão completa e executável.
• /integrations/gotenberg/security-and-operations/ — como operar a dependência do Gotenberg com segurança.
• /integrations/gotenberg/boot-and-discovery/ — montagem automática pelo framework.