Escolha uma integração

Use esta página para relacionar seu caso de uso à integração adequada. Cada recomendação se baseia exclusivamente na descrição do composer.json do pacote e em seu propósito declarado, ambos lidos diretamente do repositório de origem. Quando duas integrações se sobrepõem, esta página indica o fator que as distingue para que você possa escolher com confiança.

Encontre a linha correspondente à sua situação e comece por ela.

Comece por aqui: o que você tem?

Você tem …	Use	Por quê (propósito verificado)
Uma aplicação Laravel 12	`nextpdf/laravel`	Integração com o framework Laravel: service provider, facade e helpers de resposta em Portable Document Format (PDF).
Uma aplicação Symfony 7	`nextpdf/symfony`	Bundle do Symfony: serviços de injeção de dependência (DI) e helpers de resposta em PDF.
Uma aplicação CodeIgniter 4	`nextpdf/codeigniter`	Serviços do CodeIgniter 4, wrapper de biblioteca e helpers de resposta em PDF.
Uma aplicação PHP sem framework	`nextpdf/core` diretamente	Nenhuma integração com framework é necessária; o engine é uma biblioteca simples.
HTML que precisa de um engine de Cascading Style Sheets (CSS) de navegador, e você pode executar o Chrome	`nextpdf/artisan`	Renderizador via Chrome DevTools Protocol (CDP) para HTML que precisa de layout CSS de nível de navegador.
Um documento do Office para converter, como DOCX, XLSX ou ODT	`nextpdf/gotenberg`	Conversão de Office para PDF por meio de um microsserviço Gotenberg.
A necessidade de renderizar sem operar nenhum processo de navegador	`nextpdf/cloudflare`	Renderização serverless por meio da Cloudflare Browser Rendering API na edge.
Código escrito para uma biblioteca PDF legada	`nextpdf/compat-legacy`	Camada de compatibilidade para biblioteca PDF legada; chame o NextPDF sem reescrever os pontos de chamada.
Um runtime limitado ao PHP 8.1 / 7.4	`nextpdf/backport-builder`	Pipeline de downgrade do Rector que compila um alvo 8.1 / 7.4 do engine.
Chamadores remotos, outra linguagem ou um sistema de inteligência artificial (AI)	`nextpdf/server`	NextPDF Connect: superfície de Representational State Transfer (REST), gRPC e Model Context Protocol para execução remota.

Quando duas integrações poderiam atender

Renderizando HTML para PDF: Artisan vs Gotenberg vs Cloudflare vs core

As três pontes de renderização transformam markup em PDF. Elas diferem pela forma como operam, não pela qualidade. Use essa diferença operacional como fator decisivo.

nextpdf/artisan controla o Chrome headless pelo Chrome DevTools Protocol. Ele precisa de um processo do Chrome que a aplicação consiga alcançar. Escolha-o quando você puder operar esse processo e o documento precisar de um engine de CSS de navegador.
nextpdf/gotenberg chama um microsserviço Gotenberg fora do processo por HTTP. Escolha-o quando a renderização precisar ser isolada em seu próprio serviço ou quando a entrada for um documento do Office. O Gotenberg é o único dos três cujo propósito declarado inclui conversão de Office para PDF.
nextpdf/cloudflare chama a Cloudflare Browser Rendering API. Escolha-o quando você quiser renderização edge/serverless sem nenhum processo de navegador para executar ou aplicar patch.
O pipeline de HTML do core do NextPDF em processo não precisa de nenhum dos itens acima. Use uma ponte de renderização apenas quando o pipeline em processo não conseguir fornecer a fidelidade de layout ou o isolamento de processo de que o documento precisa. Uma ponte delega essa etapa de propósito; ela não é o caminho padrão.

As duas pontes HTTP (nextpdf/gotenberg, nextpdf/cloudflare) precisam de um cliente HTTP PSR-18 fornecido pelo host. As respectivas receitas tratam uma falha de transporte e um status HTTP sem sucesso como resultados distintos.

Convertendo um documento do Office

nextpdf/gotenberg é a integração cuja descrição verificada do composer.json menciona a conversão de Office para PDF. As outras pontes de renderização descrevem renderização de HTML, não entrada em formato Office. Se a origem for DOCX/XLSX/ODT, use esta integração.

Migrando de uma biblioteca PDF legada

Pelo propósito declarado, o nextpdf/compat-legacy é uma camada de compatibilidade para bases de código escritas para uma biblioteca PDF legada. Ele permite que pontos de chamada existentes chamem o NextPDF antes de você reescrevê-los. Trate-o como um auxílio de migração com remoção planejada, não como uma dependência permanente de runtime. Código novo deve chamar o nextpdf/core (ou a integração de framework relevante) diretamente.

Executando no PHP 8.1 ou 7.4

Todo pacote do ecossistema declara PHP >=8.4 <9.0. O nextpdf/backport-builder existe exatamente para essa restrição: seu propósito declarado é um pipeline de downgrade do Rector que compila um artefato PHP 8.1+ (e um alvo 7.4). É uma ferramenta de build, não uma dependência de runtime da aplicação. Execute o builder para produzir o engine com backport e, em seguida, implante esse engine.

Um chamador não PHP ou um agente de AI

nextpdf/server (NextPDF Connect) expõe o engine por meio de uma REST API, um serviço gRPC e o Model Context Protocol. Escolha-o quando o chamador for remoto, estiver em outra linguagem ou for um sistema de AI que consome um endpoint de ferramenta em vez de uma biblioteca PHP. Uma aplicação PHP no mesmo processo deve usar o nextpdf/core ou uma integração de framework, em vez de adicionar um salto de rede.

Usando mais de uma integração em conjunto

Uma integração de framework e uma ponte de renderização atuam em camadas diferentes, então você pode instalar ambas. A integração de framework cuida da configuração do container e da resposta HTTP; a ponte de renderização cuida do backend de renderização. Ao resolver um conjunto combinado de dependências, verifique quais versões do nextpdf/core cada pacote aceita. A referência de restrição do core no índice do cookbook de integrações é a fonte da verdade. As receitas de cada combinação ficam nos repositórios relevantes e são linkadas a partir desse índice.

Veja também

Cookbook de integrações — referência de pacotes e de restrições do core, além do índice de links de receitas.
Convenções de receitas — o contrato que toda receita executável segue.