Integração do NextPDF com Gotenberg

Visão geral

Esta página mostra como conectar a ponte ao restante da aplicação. Instale o pacote, integre-o e depois envie o Portable Document Format (PDF) convertido para um pipeline de pós-processamento do NextPDF. A ponte converte um documento do Office em PDF; o pipeline cuida de tudo o que vem depois da conversão. Para entender o design por trás dessa integração, consulte /integrations/gotenberg/boot-and-discovery/.

Instalação

composer require nextpdf/gotenberg

Ao instalar este pacote, você também instala nextpdf/core ^3.0 e os contratos PHP Standards Recommendation (PSR) Hypertext Transfer Protocol (HTTP). Instale um cliente PSR-18 e fábricas PSR-17 como pacotes separados. A ponte depende apenas das interfaces, então você pode escolher as bibliotecas concretas. Para ver todas as etapas de instalação, incluindo como executar o serviço Gotenberg por Hypertext Transfer Protocol Secure (HTTPS), consulte /integrations/gotenberg/install/.

Integração

Crie a ponte com um objeto de configuração e os colaboradores PSR. Injete também uma fábrica de respostas; é ela que habilita o transporte com pinning de Domain Name System (DNS) e pinning de Transport Layer Security (TLS):

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: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

A ponte exige HTTPS para a URL configurada. Ela rejeita http:// simples antes de enviar qualquer requisição. Execute o Gotenberg atrás de uma terminação TLS e depois aponte a ponte para o endpoint HTTPS.

Bindings de container

Registre três entradas no container host: o GotenbergConfig construído a partir da fonte de configuração, o cliente PSR-18 junto com as fábricas PSR-17 e o GotenbergBridge, montado a partir dessas dependências. Este pacote não fornece bindings próprios. O registro nativo do framework fica nos pacotes dedicados de integração com framework. Consulte /integrations/gotenberg/boot-and-discovery/.

Configuração

Todos os campos do descritor de serviço e os limites ficam em GotenbergConfig. Eles cobrem a URL da application programming interface (API), o timeout, o limite de tamanho, o bearer token e os pins TLS. As opções por requisição, landscape e nativePageRanges, ficam no tipo de payload. /integrations/gotenberg/configuration/ documenta cada campo, com tipo, valor padrão e efeito.

Conectar o PDF convertido a um pipeline do NextPDF

Um fluxo típico de ponta a ponta é:

1. Converta o documento do Office com convertFile() ou convertString().
2. Pegue $result->pdfData, que contém os bytes brutos do PDF, e carregue-o em um documento do NextPDF.
3. Aplique o pós-processamento, como montagem de páginas, marca d’água, conversão para PDF/A ou assinaturas digitais.

A etapa 3 pertence ao NextPDF, não à ponte. O pacote nextpdf/premium fornece assinatura, perfis PDF/A e marca d’água. Mantenha a conversão e o pós-processamento como estágios separados para conseguir diagnosticar cada falha individualmente.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

O suporte a PDF Advanced Electronic Signatures (PAdES) da edição Pro é apenas a baseline B-B. Ele não fornece B-T, B-LT nem B-LTA. Converter um documento por meio desta ponte não implica nenhuma capacidade de timestamp ou de validação de longo prazo.

Teste de fumaça

Depois de fazer a integração, confirme que ela funciona sem converter um documento real:

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

isAvailable() valida a URL sem tráfego de rede. Em seguida, envia uma requisição HEAD para <apiUrl>/health. Depois disso, converta um pequeno documento comprovadamente válido. Isso exercita todo o caminho multipart até <apiUrl>/forms/libreoffice/convert e valida a resposta.

Pontos de entrada da API pública

A superfície pública usada por esta integração é:

• GotenbergConfig — descritor de serviço imutável e limites; fromArray() o constrói a partir de um array de configuração.
• GotenbergBridge::convertFile(string $path) — converte um arquivo em disco.
• GotenbergBridge::convertString(string $bytes, string $fileName) — converte bytes mantidos em memória.
• GotenbergBridge::isAvailable() — verificação de prontidão que não lança exceção.
• GotenbergConvertResult — carrega pdfData, sourceFormat, isValid() e size().
• GotenbergConvertException — o tipo de exceção da camada de conversão.

O contrato completo está em /integrations/gotenberg/configuration/ e /integrations/gotenberg/troubleshooting/. Ele cobre a seleção de transporte e o catálogo de exceções.

Consulte também

• /integrations/gotenberg/boot-and-discovery/ — por que a integração é feita dessa forma.
• /integrations/gotenberg/quickstart/ — uma primeira conversão guiada.
• /integrations/gotenberg/production-usage/ — segredos, novas tentativas, timeouts, observabilidade.
• /integrations/gotenberg/install/ — instalação do pacote e do serviço Gotenberg.