Livro de receitas das integrações

O core do NextPDF renderiza Portable Document Format (PDF) 2.0 a partir de PHP. Os nove pacotes de integração conectam esse motor a um framework, a um backend de renderização, a uma base de código legada, a um pipeline de build ou a um serviço de rede. Esta página explica a finalidade de cada integração, lista o nome do pacote e a restrição de versão do core (lida diretamente do composer.json de cada um) e aponta para a receita de início rápido de cada integração.

Esta página é um índice; portanto, não faz nenhuma afirmação sobre o comportamento de qualquer integração. Cada repositório de integração é responsável pelas próprias receitas, e o agregador as publica neste site. Para uma recomendação orientada por caso de uso, leia Escolha uma integração. Para conhecer o contrato que toda receita executável segue, leia Convenções de receitas.

Os cinco formatos de integração

Os nove pacotes se dividem em cinco formatos. Cada formato indica o tipo de problema que a integração resolve.

Integrações de framework conectam o NextPDF ao container de serviços e ao ciclo de vida das requisições de um framework de aplicação: nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter. Você instala o pacote, resolve um serviço e retorna uma resposta em PDF.
Pontes de renderizador enviam a etapa de HTML-para-PDF ou de Office-para-PDF para um backend de renderização externo, em vez de executá-la no pipeline em processo: nextpdf/artisan (Chrome headless sobre o Chrome DevTools Protocol), nextpdf/gotenberg (um microsserviço Gotenberg), nextpdf/cloudflare (Cloudflare Browser Rendering na edge).
Um shim de compatibilidade permite que uma base de código escrita para uma biblioteca de PDF legada chame o NextPDF antes que você a reescreva: nextpdf/compat-legacy.
Uma ferramenta de build produz um backport do NextPDF para PHP 8.1 / 7.4, destinado a runtimes que não conseguem executar a 8.4: nextpdf/backport-builder.
Um serviço de rede expõe o NextPDF via Representational State Transfer (REST), gRPC e Model Context Protocol para sistemas de IA e chamadores remotos: nextpdf/server (distribuído como NextPDF Connect).

As pontes de renderizador que falam Hypertext Transfer Protocol (HTTP) (nextpdf/gotenberg, nextpdf/cloudflare e o caminho de cliente HTTP em nextpdf/laravel) dependem de um cliente HTTP PHP Standard Recommendation 18 (PSR-18) fornecido pela aplicação host. De acordo com a PSR-18 §4, o cliente lança uma exceção de cliente tipada apenas quando não consegue enviar a requisição de modo algum. Uma resposta HTTP 4xx ou 5xx é um valor de retorno normal, não uma exceção, conforme a mesma cláusula PSR-18 §4. Receitas que chamam um renderizador remoto tratam erros de transporte e status de insucesso como casos separados.

Referência de pacote e restrição de versão do core

Todos os valores abaixo vêm do composer.json do pacote indicado (a fonte autoritativa). A restrição de versão do core é o requisito de nextpdf/core declarado pelo pacote. O nextpdf/backport-builder não declara nenhum requisito de nextpdf/core porque transforma o código-fonte do motor, em vez de depender dele em tempo de execução.

Integração	Pacote	Formato	Restrição de core	Receita
Laravel	`nextpdf/laravel`	Framework	`^3.0 \|\| ^5.2`	Guia de início rápido do Laravel
Symfony	`nextpdf/symfony`	Framework	`^3.0 \|\| ^5.2`	Guia de início rápido do Symfony
CodeIgniter 4	`nextpdf/codeigniter`	Framework	`^3.0 \|\| ^5.2`	Guia de início rápido do CodeIgniter
Artisan (Chrome)	`nextpdf/artisan`	Ponte de renderizador	`^3.0 \|\| ^5.2`	Guia de início rápido do Artisan
Gotenberg	`nextpdf/gotenberg`	Ponte de renderizador	`^3.0`	Guia de início rápido do Gotenberg
Cloudflare	`nextpdf/cloudflare`	Ponte de renderizador	`^3.0`	Guia de início rápido do Cloudflare
Compat (legado)	`nextpdf/compat-legacy`	Shim de compatibilidade	`^3.0`	Guia de início rápido do TCPDF-compat
Backport builder	`nextpdf/backport-builder`	Ferramenta de build	não se aplica	Guia de início rápido do Backport
Connect (server)	`nextpdf/server`	Serviço de rede	`^3.0`	Guia de início rápido do Connect

O NextPDF distribui o nextpdf/server sob o nome de produto NextPDF Connect; as receitas desse pacote ficam sob o slug de nível superior connect. O nextpdf/compat-legacy faz parte da família compat; as receitas dele ficam sob o slug tcpdf-compat, nomeado em referência à superfície que ele emula.

Todo pacote requer PHP >=8.4 <9.0 no próprio runtime. O nextpdf/backport-builder existe para produzir artefatos que rodam em PHP 8.1 (e um alvo 7.4). O motor resultante com backport, não o builder, é o que roda no runtime mais antigo.

Para que serve cada integração

Integrações de framework

nextpdf/laravel — um service provider, uma facade e helpers de resposta em PDF para Laravel 12. Use-o quando a aplicação for um app Laravel e você quiser resolver o NextPDF pelo container e retorná-lo como uma resposta HTTP sem configuração manual. Receita: Guia de início rápido do Laravel.
nextpdf/symfony — um bundle para Symfony 7 com serviços de injeção de dependência e helpers de resposta em PDF. Use-o quando a aplicação for um app Symfony. O bundle registra o motor como um serviço e se integra às respostas do symfony/http-foundation. Receita: Guia de início rápido do Symfony.
nextpdf/codeigniter — um serviço, um wrapper de biblioteca e helpers de resposta em PDF para CodeIgniter 4. Use-o quando a aplicação for um app CodeIgniter 4 e você quiser deixar o NextPDF disponível pelo service locator do framework. Receita: Guia de início rápido do CodeIgniter.

Pontes de renderizador

nextpdf/artisan — um renderizador com Chrome headless sobre o Chrome DevTools Protocol. Use-o quando um documento precisar do motor de Cascading Style Sheets (CSS) de um navegador para alcançar uma fidelidade de layout que o pipeline de HTML em processo não pretende oferecer, e quando você puder executar um processo do Chrome próximo à aplicação. Receita: Guia de início rápido do Artisan.
nextpdf/gotenberg — conversão de Office-para-PDF e HTML-para-PDF por meio de um microsserviço Gotenberg. Use-o quando a entrada for um documento do Office ou quando a renderização precisar rodar fora do processo, em um serviço separado. Ele se comunica por HTTP por meio de um cliente PSR-18 fornecido pelo host. Receita: Guia de início rápido do Gotenberg.
nextpdf/cloudflare — renderização serverless por meio da API Cloudflare Browser Rendering. Use-o quando a renderização precisar rodar na edge, sem operar nenhum processo de navegador de longa duração. Ele se comunica por HTTP por meio de um cliente PSR-18 fornecido pelo host. Receita: Guia de início rápido do Cloudflare.

Shim de compatibilidade

nextpdf/compat-legacy — uma camada de compatibilidade para bases de código escritas para uma biblioteca de PDF legada. Use-o para chamar o NextPDF a partir de código existente antes de você reescrever os pontos de chamada. É um auxílio de migração, não uma dependência permanente. Receita: Guia de início rápido do TCPDF-compat.

Ferramenta de build

nextpdf/backport-builder — um pipeline de downgrade baseado em Rector que produz um build do NextPDF para PHP 8.1 (e um alvo 7.4). Use-o quando um runtime não puder migrar para o PHP 8.4 e você ainda precisar do motor nesse ambiente. É infraestrutura de build, não uma dependência de runtime de uma aplicação. Receita: Guia de início rápido do Backport.

Serviço de rede

nextpdf/server (NextPDF Connect) — expõe o NextPDF por meio de uma API REST, um serviço gRPC e o Model Context Protocol. Use-o quando os chamadores forem remotos, usarem outra linguagem ou forem sistemas de IA que precisam de um endpoint de ferramenta em vez de uma biblioteca PHP. Receita: Guia de início rápido do Connect.

Como os slugs das receitas são organizados

As receitas ficam sob /integrations/<integration>/<recipe>/, onde <integration> é o nome curto da tabela de referência acima (as receitas do Connect ficam sob o slug de nível superior connect). A primeira receita que toda integração publica se chama quickstart; receitas posteriores usam segmentos <recipe> adicionais sob a mesma raiz. Este índice não faz nenhuma afirmação sobre o comportamento de qualquer página de destino. Ele registra apenas os fatos do pacote verificados a partir do composer.json e o slug que as receitas de cada repositório ocupam.

Veja também

Escolha uma integração — uma matriz de decisão que mapeia casos de uso para integrações.
Convenções de receitas — o contrato que toda receita executável neste livro de receitas segue.