Guía de decisión de integración

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

De un vistazo

El ecosistema NextPDF consta de un motor central pequeño y un conjunto de paquetes especializados: puentes de framework, dos renderizadores HTML, un renderizador edge y un servidor de ejecución. Esta página relaciona casos de uso reales con el paquete que mejor encaja, según lo que cada paquete proporciona realmente. La elección sigue siendo una decisión basada en evidencia, en lugar de una que esta documentación toma por el lector.

Por qué importa

Elegir la integración equivocada sale caro de formas que no se perciben de inmediato. Si se elige un renderizador de navegador remoto cuando el motor en proceso habría representado el documento sin problemas, se añade un salto de red y una dependencia de disponibilidad a cada PDF. Si se elige el motor en proceso para un documento que realmente necesita un motor de maquetación de navegador completo, el resultado es un archivo sutilmente incorrecto. El paquete adoptado determina la latencia, los modos de fallo y la superficie operativa, así que conviene que la decisión sea explícita.

La versión breve

Empezar por el motor central. Todo lo demás es aditivo. Si el motor en proceso representa el documento correctamente, no hace falta ningún paquete de renderizado en absoluto.
El puente de framework sigue al framework, no al documento. Las integraciones para Laravel, Symfony y CodeIgniter existen para proporcionar una fachada o un factory, una respuesta PDF, generación en cola y autodescubrimiento; no cambian lo que el motor puede representar.
Usar un renderizador solo cuando la fidelidad de CSS requiera un navegador. Artisan (Chrome local) y Cloudflare (navegador edge) existen exactamente para eso; Gotenberg existe para incorporar documentos de Office.
Usar Connect cuando el consumidor sea un servicio o un agente de IA, no una llamada PHP. Expone el motor sobre MCP, REST y gRPC con una verificación de aprobación humana para las operaciones peligrosas.

Cómo lo aborda NextPDF

El ecosistema está estratificado deliberadamente para que cada paquete tenga una única función. El motor central representa PDF en proceso. Un puente de framework adapta ese motor a las convenciones de un framework. Un paquete de renderizado delega la maquetación de HTML o de Office en un motor externo cuando el motor en proceso no es la herramienta adecuada. Connect convierte el motor en un servicio de red. Ninguno de estos paquetes se solapa con la responsabilidad de otro, y eso hace que la decisión sea manejable. No se está eligiendo entre herramientas que compiten entre sí. Se están componiendo herramientas complementarias.

La decisión se toma mejor según el caso de uso. La tabla relaciona cada escenario con el paquete que encaja e indica la contrapartida aceptada.

Caso de uso	Paquete que encaja	Lo que proporciona realmente	La contrapartida que aceptas
PDF en una aplicación Laravel	`nextpdf/laravel`	Proveedor de servicios autodescubierto, fachada `Pdf`, `PdfResponse` (en línea/descarga/transmitido, cabeceras OWASP), un `GeneratePdfJob` en cola con tries/timeout/backoff, registros bloqueados seguros para Octane	Una dependencia de Laravel 12; las capacidades del motor no cambian
PDF en una aplicación Symfony	`nextpdf/symfony`	Bundle autorregistrado, `PdfFactory` inyectable, `PdfResponse`, un manejador opcional de Messenger para la generación asíncrona	Una dependencia del bundle de Symfony 7.2; las capacidades no cambian
PDF en una aplicación CodeIgniter 4	`nextpdf/codeigniter`	Asistente `service('pdf')` / `pdf()`, una biblioteca `Pdf` que envuelve un `Document` desechable, un `PdfResponse`, un trabajo en cola opcional	Una dependencia de CodeIgniter 4.6; las capacidades no cambian
El documento necesita CSS de navegador completo (flex/grid/fuentes web) junto al proceso	`nextpdf/artisan`	Chrome headless mediante CDP, representado y luego reimportado como un Form XObject para que el texto siga siendo seleccionable; un pool de navegadores	Un entorno de ejecución de Chrome y su coste de memory/process en el host
Documentos de Office (`.docx`, `.xlsx`) a PDF	`nextpdf/gotenberg`	Un puente PSR-18 a un microservicio Gotenberg con transporte reforzado contra SSRF y con IP fijada	Un servicio Gotenberg externo y una dependencia de red
HTML→PDF en el edge / sin Chrome local	`nextpdf/cloudflare`	Cloudflare Browser Rendering mediante transporte fijado, con repliegue opcional a Chrome local	Una cuenta de Cloudflare y una dependencia de red; el repliegue necesita Artisan
Motor consumido por un servicio o un agente de IA	`nextpdf/server` (Connect)	Un único motor sobre MCP (stdio), REST (OpenAPI 3.1) y gRPC; descubrimiento de herramientas por dependencia blanda; una verificación de confirmación humana para las herramientas de alto riesgo	Operar una superficie de servicio; disciplina de ejecución determinista

Lo que dice la evidencia

Esta página es editorial —una decisión de enrutamiento—, pero el enrutamiento se fundamenta en lo que el manifiesto y las clases principales de cada paquete contienen realmente.

Los puentes son reales y paralelos. Cada uno declara su dependencia de framework y su autorregistro en su composer.json (extra.laravel.providers, extra.symfony.bundles, el Registrar de CodeIgniter). Cada uno incluye además un PdfResponse, un enlace de documento desechable y un trabajo en cola opcional. Ninguno de ellos añade una capacidad de renderizado: adaptan el mismo motor. Los renderizadores son reales y distintos. Artisan depende de chrome-php/chrome y reimporta el PDF de Chrome como un Form XObject para mantener el texto seleccionable. Gotenberg y Cloudflare son puentes HTTP PSR-18 con transportes explícitamente reforzados contra SSRF y con IP fijada. Cloudflare puede replegarse a Artisan cuando el Worker es inalcanzable. El composer.json de Connect declara los tres transportes y un modelo de dependencia blanda en el que las herramientas aparecen a medida que se instalan sus paquetes, regido por un modelo de riesgo de cuatro niveles con una verificación de confirmación humana.

El enrutamiento de esta página está respaldado por estándares en su estructura: Spec: ISO 24495-1:2023, §5 señala que los lectores deberían poder determinar rápidamente si el contenido sirve a su propósito (chunk), y Spec: ISO/IEC/IEEE 26514:2022, §3.x222 exige que los enlaces y las referencias indiquen su destino ; por eso la tabla nombra el paquete concreto y la contrapartida en lugar de referirse vagamente a «una integración».

Ejemplo práctico

La decisión es una secuencia de preguntas honestas, no una comparación de características. El siguiente esquema resuelve los casos habituales.

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.

La lección está en la estructura: el renderizado y la invocación son ejes separados. Responderlas como una sola pregunta es como los equipos acaban con un renderizador remoto que no hacía falta o con un puente que no resuelve su problema de fidelidad.

Concepto erróneo habitual

La idea equivocada más extendida es «Necesito un paquete de renderizado para generar PDF.» No hace falta. El motor central genera PDF en proceso. Los paquetes de renderizado existen solo para el caso específico en el que se requiere un motor de maquetación de calidad de navegador o la fuente es un documento de Office. Cuando el motor en proceso ya produce el archivo correcto, adoptar un renderizador por reflejo añade una dependencia en tiempo de ejecución y un modo de fallo sin ningún beneficio.

La idea equivocada inversa es «el puente de framework desbloquea capacidades.» No las desbloquea. Un puente cambia cómo se llama al motor —fachada, factory, respuesta, trabajo en cola— no lo que puede producir. La firma, PDF/A y las facturas estructuradas son cuestiones de nivel y de motor, idénticas tanto si se llama a través de un puente como directamente.

Límites y fronteras

Esta página enruta; no compara rendimiento ni clasifica. Indica lo que cada paquete proporciona y la contrapartida. Elegir entre ellos depende de las restricciones propias.
Las capacidades de los paquetes se leen de sus manifiestos y de sus clases principales en un momento concreto. La documentación propia de cada paquete debe tratarse como la fuente autorizada para su API actual. Esta guía es el mapa, no la especificación.
No se ofrece ni se da a entender ninguna comparación con la competencia. El único tema es el ecosistema NextPDF y cómo encajan sus partes entre sí.
El puente de framework y el renderizador son elecciones independientes. Un puente no amplía la capacidad del motor; un renderizador no depende de un framework.
Los renderizadores externos añaden una dependencia de disponibilidad. Gotenberg y Cloudflare introducen una llamada de red y un servicio que hay que operar; esa es la contrapartida aceptada, no un coste oculto.
Las capacidades restringidas por nivel son ortogonales a la integración. Las funciones comerciales se desbloquean por el nivel, no por ningún puente ni renderizador; consulta la frontera más abajo.

Ecosystem packages and tiering — edition availability
Edition	Availability
Core	Cada paquete de integración (puentes, Artisan, Gotenberg, Cloudflare, Connect) funciona con Core y es Apache-2.0. Adaptan o exponen el motor; no restringen funciones.
Pro	Las capacidades comerciales (firma PAdES baseline, PDF/A, códigos de barras avanzados ) se desbloquean por el nivel y luego están disponibles a través de cualquier integración, no por cambiar de integración.
Enterprise	Las facturas estructuradas, las políticas de validación y la verificación de confirmación humana de Connect para las herramientas de alto riesgo son capacidades de nivel, igualmente independientes de la integración.

Documentos relacionados

El pipeline de HTML — qué cubre el motor de CSS en proceso, para saber cuándo es realmente necesario un renderizador de navegador.
Cuándo no usar NextPDF — la frontera honesta sobre los problemas de documentos para los que el motor no es la herramienta adecuada.
Los fundamentos de PHP 8.4 — la base del entorno de ejecución que todos los paquetes comparten y lo que preserva la ruta de backport.

Glosario

Motor central — nextpdf/core, el motor de PDF 2.0 en proceso sobre el que se construye cualquier otro paquete.
Puente de framework — un paquete de integración (Laravel/Symfony/CodeIgniter) que adapta el motor a las convenciones de un framework sin cambiar sus capacidades.
Paquete de renderizado — un paquete que delega la maquetación de HTML o de Office en un motor externo (Artisan/Cloudflare/Gotenberg) cuando el motor en proceso no es la herramienta adecuada.
Form XObject — un fragmento de contenido PDF reutilizable; Artisan importa una página representada por el navegador como un Form XObject para que su texto siga siendo seleccionable.
NextPDF Connect — nextpdf/server, el paquete que expone el motor sobre MCP, REST y gRPC con una superficie de ejecución determinista.
Dependencia blanda — el modelo de Connect en el que las herramientas aparecen automáticamente a medida que se instalan paquetes opcionales de NextPDF, sin ningún cambio de código.