Guia de decisão de integração

Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 Evidence ¶ Editorial Evidence: Editorial

Em resumo

O ecossistema NextPDF combina um pequeno engine central com um conjunto de pacotes focados: bridges de framework, dois renderizadores HTML, um renderizador de edge e um servidor de execução. Esta página mapeia casos de uso reais para o pacote mais adequado, com base no que cada pacote realmente contém. A escolha continua sendo sua, fundamentada em evidências, e não sugerida pela documentação.

Por que isso importa

Escolher a integração errada custa caro de uma forma que nem sempre aparece de imediato. Escolha um renderizador de navegador remoto quando o engine in-process teria renderizado o documento corretamente, e você acrescenta um salto de rede e uma dependência de disponibilidade a cada PDF. Escolha o engine in-process para um documento que realmente precisa de um engine completo de layout de navegador, e você obtém um arquivo sutilmente incorreto. O pacote que você adota molda a latência, os modos de falha e a superfície operacional; portanto, a decisão merece ser explícita.

A versão curta

• Comece pelo engine central. Todo o resto é aditivo. Se o engine in-process renderiza o documento corretamente, você não precisa de nenhum pacote de renderizador.
• O bridge de framework acompanha o framework, não o documento. As integrações para Laravel, Symfony e CodeIgniter existem para oferecer uma facade ou factory, uma resposta PDF, geração em fila e descoberta automática — elas não mudam o que o engine consegue renderizar.
• Use um renderizador apenas quando a fidelidade de CSS exigir um navegador. Artisan (Chrome local) e Cloudflare (navegador na edge) existem exatamente para isso; o Gotenberg existe para trazer documentos do Office.
• Use o Connect quando o chamador for um serviço ou um agente de IA, não uma chamada PHP. Ele expõe o engine via MCP, REST e gRPC com um portão de aprovação humana para operações perigosas.

Como o NextPDF aborda isso

O ecossistema é deliberadamente organizado em camadas, de modo que cada pacote tem uma única função. O engine central renderiza PDF in-process. Um bridge de framework adapta esse engine às convenções de um framework. Um pacote de renderizador delega o layout de HTML ou do Office a um engine externo quando o in-process não é a ferramenta certa. O Connect transforma o engine em um serviço de rede. Nenhum desses pacotes se sobrepõe à responsabilidade de outro, e é isso que torna a decisão tratável. Você não está escolhendo entre ferramentas concorrentes. Você está compondo ferramentas complementares.

Tome a decisão em função do caso de uso. A tabela mapeia cada cenário para o pacote adequado e declara a troca que você aceita.

Caso de uso	Pacote que se encaixa	O que ele de fato fornece	A troca que você aceita
PDF em um app Laravel	nextpdf/laravel	Service provider descoberto automaticamente, facade Pdf, PdfResponse (inline/download/streamed, cabeçalhos OWASP), um GeneratePdfJob em fila com tries/timeout/backoff, registries com lock seguros para Octane	Uma dependência do Laravel 12; os recursos do engine permanecem inalterados
PDF em um app Symfony	nextpdf/symfony	Bundle registrado automaticamente, PdfFactory injetável, PdfResponse, um handler opcional do Messenger para geração assíncrona	Uma dependência de bundle do Symfony 7.2; recursos inalterados
PDF em um app CodeIgniter 4	nextpdf/codeigniter	service('pdf') / pdf() helper, uma biblioteca Pdf que encapsula um Document descartável, um PdfResponse, um job em fila opcional	Uma dependência de CodeIgniter 4.6; recursos inalterados
O documento precisa de CSS completo de navegador (flex/grid/web fonts) junto ao in-process	nextpdf/artisan	Chrome headless via CDP, renderizado e depois reimportado como um Form XObject para que o texto permaneça selecionável; um pool de navegadores	Um runtime do Chrome e seu custo de memory/process no host
Documentos do Office (.docx, .xlsx) para PDF	nextpdf/gotenberg	Um bridge PSR-18 para um microsserviço Gotenberg com transporte reforçado contra SSRF e com IP fixado	Um serviço Gotenberg externo e uma dependência de rede
HTML→PDF na edge / sem Chrome local	nextpdf/cloudflare	Cloudflare Browser Rendering via transporte fixado, com fallback opcional para Chrome local	Uma conta Cloudflare e uma dependência de rede; o fallback precisa do Artisan
Engine consumido por um serviço ou agente de IA	nextpdf/server (Connect)	Um único engine via MCP (stdio), REST (OpenAPI 3.1) e gRPC; descoberta de ferramentas por dependência leve; um portão de confirmação humana para ferramentas de alto risco	Operar uma superfície de serviço; disciplina para execução determinística

Human-factors note: Human-factors note

Estas são duas decisões independentes, e as pessoas costumam misturá-las. O bridge de framework é escolhido pelo framework que você já usa — ele não expande nem restringe o que o engine renderiza. O renderizador é escolhido pelo documento. A pergunta decisiva é se o engine de CSS in-process é suficiente, ou se o documento realmente precisa de um engine de layout de navegador. Você pode precisar de um bridge de framework e de nenhum renderizador, de um renderizador e de nenhum bridge, de ambos ou de nenhum. Tratar as duas como uma só pergunta é o erro de integração mais comum, e é por isso que esta página as separa.

O que as evidências dizem

Esta página é editorial — uma decisão de roteamento —, mas o roteamento está fundamentado no que o manifesto e as classes principais de cada pacote contêm.

Evidence ¶ Editorial Evidence: Editorial

Os bridges são reais e paralelos. Cada um declara sua dependência de framework e o auto-registro em seu composer.json (extra.laravel.providers, extra.symfony.bundles, o Registrar do CodeIgniter). Cada um também entrega um PdfResponse, um binding de documento descartável e um job em fila opcional. Nenhum deles adiciona um recurso de renderização — eles adaptam o mesmo engine. Os renderizadores são reais e distintos. O Artisan depende de chrome-php/chrome e reimporta o PDF do Chrome como um Form XObject para manter o texto selecionável. Gotenberg e Cloudflare são bridges HTTP PSR-18 com transportes explicitamente reforçados contra SSRF e com IP fixado. O Cloudflare pode recorrer ao Artisan quando o Worker está inacessível. O composer.json do Connect declara os três transportes e um modelo de dependência leve no qual as ferramentas aparecem conforme seus pacotes são instalados, governado por um modelo de risco de quatro níveis com um portão de confirmação humana.

A forma como esta página roteia você é respaldada por padrões na própria estrutura: Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 diz que os leitores devem conseguir determinar rapidamente se o conteúdo atende ao seu objetivo, e Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x222 ISO/IEC/IEEE 26514:2022 §3.x222 exige que links e referências declarem seu destino — e é por isso que a tabela nomeia o pacote concreto e a troca, em vez de se referir vagamente a “uma integração”.

Exemplo prático

A decisão é uma sequência de perguntas honestas, não uma comparação de recursos. O fluxo a seguir resolve os casos comuns.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

A estrutura é a lição: renderização e invocação são eixos separados. Responder às duas juntas é como equipes acabam com um renderizador remoto de que não precisavam, ou com um bridge que não resolve o problema de fidelidade.

Equívoco comum

O equívoco dominante é “preciso de um pacote de renderizador para gerar PDFs.” Você não precisa. O engine central gera PDF in-process. Os pacotes de renderizador existem apenas para o caso específico em que um engine de layout de nível de navegador é exigido ou a origem é um documento do Office. Quando o engine in-process já produz o arquivo correto, adotar um renderizador por reflexo acrescenta uma dependência de runtime e um modo de falha sem nenhum benefício.

O equívoco oposto é “o bridge de framework desbloqueia recursos.” Ele não desbloqueia. Um bridge muda como você chama o engine — facade, factory, response, job em fila — não o que ele consegue produzir. Assinatura, PDF/A e faturas estruturadas são preocupações de tier e de engine, idênticas quer você chame por um bridge, quer chame diretamente.

Limites e fronteiras

• Esta página roteia; ela não faz benchmark nem ranqueia. Ela declara o que cada pacote fornece e a troca. Escolher entre eles é uma decisão sua, conforme suas restrições.
• Os recursos de cada pacote são lidos de seus manifestos e classes principais em um dado momento. Trate a documentação de cada pacote como a fonte autorizada sobre sua API atual. Este guia é o mapa, não a especificação.
• Nenhuma comparação com concorrentes é oferecida ou sugerida. O único assunto é o ecossistema NextPDF e como suas partes se encaixam.
• O bridge de framework e o renderizador são escolhas independentes. Um bridge não expande o recurso do engine; um renderizador não depende de um framework.
• Renderizadores externos acrescentam uma dependência de disponibilidade. Gotenberg e Cloudflare introduzem uma chamada de rede e um serviço para operar; essa é a troca aceita, não um custo oculto.
• Os recursos limitados por tier são ortogonais à integração. Os recursos comerciais são desbloqueados pelo tier, não por qualquer bridge ou renderizador; veja a fronteira abaixo.

Ecosystem packages and tiering — edition availability

Edition	Availability
Core	○ Todos os pacotes de integração (bridges, Artisan, Gotenberg, Cloudflare, Connect) funcionam com o Core e são Apache-2.0. Eles adaptam ou expõem o engine; eles não restringem recursos.
Pro	○ Os recursos comerciais (PAdES baseline signing, PDF/A, códigos de barras avançados barcodes) são desbloqueados pelo tier e ficam então disponíveis através de qualquer integração, não pela troca de integração.
Enterprise	○ Faturas estruturadas, políticas de validação e o portão de confirmação humana do Connect para ferramentas de alto risco são recursos de tier, igualmente independentes da integração.

Documentos relacionados

• O pipeline de HTML — o que o engine de CSS in-process cobre, para você saber quando um renderizador de navegador é realmente necessário.
• Quando não usar o NextPDF — a fronteira honesta sobre os problemas de documento para os quais o engine não é a ferramenta certa.
• Os fundamentos do PHP 8.4 — o piso de runtime que todos os pacotes compartilham e o que o caminho de backport preserva.

Glossário

• Engine central — nextpdf/core, o engine PDF 2.0 in-process sobre o qual todos os outros pacotes são construídos.
• Bridge de framework — um pacote de integração (Laravel/Symfony/CodeIgniter) que adapta o engine às convenções de um framework sem alterar seus recursos.
• Pacote de renderizador — um pacote que delega o layout de HTML ou do Office a um engine externo (Artisan/Cloudflare/Gotenberg) quando o engine in-process não é a ferramenta certa.
• Form XObject — um fragmento de conteúdo PDF reutilizável; o Artisan importa uma página renderizada pelo navegador como um deles, para que o texto permaneça selecionável.
• NextPDF Connect — nextpdf/server, o pacote que expõe o engine via MCP, REST e gRPC com uma superfície de execução determinística.
• Dependência leve — o modelo do Connect em que as ferramentas aparecem automaticamente conforme pacotes NextPDF opcionais são instalados, sem alteração de código.