Elegir una integración

Esta página asocia cada caso de uso con la integración que lo cubre. Cada recomendación se basa únicamente en la descripción del paquete en su composer.json y en su propósito declarado, leídos ambos directamente del repositorio de origen. Cuando dos integraciones se solapan, se indica el factor que las distingue y la decisión queda en manos de quien implementa.

Buscar la fila que coincida con la situación y empezar por ahí.

Empezar aquí: ¿cuál es el punto de partida?

Situación …	Usar	Por qué (propósito verificado)
Una aplicación Laravel 12	`nextpdf/laravel`	Integración con el framework Laravel: service provider, facade y helpers de respuesta PDF.
Una aplicación Symfony 7	`nextpdf/symfony`	Bundle de Symfony: servicios de DI y helpers de respuesta PDF.
Una aplicación CodeIgniter 4	`nextpdf/codeigniter`	Servicios de CodeIgniter 4, wrapper de biblioteca y helpers de respuesta PDF.
Una aplicación PHP sin framework	`nextpdf/core` directamente	No hace falta ninguna integración con un framework; el motor es una biblioteca convencional.
HTML que necesita un motor CSS de navegador, con posibilidad de ejecutar Chrome	`nextpdf/artisan`	Renderer de Chrome mediante CDP para HTML que necesita una maquetación CSS con fidelidad de navegador.
Un documento de Office para convertir, como DOCX, XLSX u ODT	`nextpdf/gotenberg`	Conversión de Office a PDF mediante un microservicio Gotenberg.
Necesidad de renderizar sin operar ningún proceso de navegador	`nextpdf/cloudflare`	Renderizado serverless mediante la Cloudflare Browser Rendering API en el edge.
Código escrito para una biblioteca de PDF heredada	`nextpdf/compat-legacy`	Capa de compatibilidad para una biblioteca de PDF heredada; llama a NextPDF sin reescribir los puntos de llamada.
Un runtime limitado a PHP 8.1 / 7.4	`nextpdf/backport-builder`	Pipeline de downgrade con Rector que genera un target 8.1 / 7.4 del motor.
Llamadores remotos, un lenguaje distinto o un sistema de IA	`nextpdf/server`	NextPDF Connect: interfaz REST, gRPC y Model Context Protocol para ejecución remota.

Cuando dos integraciones podrían encajar

Renderizar HTML a PDF: Artisan vs. Gotenberg vs. Cloudflare vs. core

Los tres puentes de renderer convierten markup en PDF. Se diferencian por cómo operan, no por la calidad; por tanto, esa diferencia operativa es el factor decisivo.

nextpdf/artisan controla headless Chrome a través del Chrome DevTools Protocol. Requiere un proceso de Chrome accesible desde la aplicación. Conviene elegirlo cuando sea posible operar ese proceso y el documento requiera un motor CSS de navegador.
nextpdf/gotenberg llama vía HTTP a un microservicio Gotenberg externo al proceso. Conviene elegirlo cuando el renderizado deba estar aislado en su propio servicio, o cuando la entrada sea un documento de Office. Gotenberg es el único de los tres cuyo propósito declarado incluye la conversión de Office a PDF.
nextpdf/cloudflare llama a la Cloudflare Browser Rendering API. Conviene elegirlo cuando se necesite renderizado edge/serverless sin ningún proceso de navegador que ejecutar ni parchear.
El pipeline HTML in-process del core de NextPDF no necesita nada de lo anterior. Usar un puente de renderer solo cuando el pipeline in-process no pueda alcanzar la fidelidad de maquetación o el aislamiento de proceso que el documento necesita. Un puente es una decisión deliberada para delegar ese paso, no la ruta predeterminada.

Los dos puentes HTTP (nextpdf/gotenberg, nextpdf/cloudflare) requieren un cliente HTTP PSR-18 proporcionado por el host. Sus recipes tratan un fallo de transporte y un estado HTTP no exitoso como resultados distintos.

Convertir un documento de Office

nextpdf/gotenberg es la integración cuya descripción verificada en su composer.json menciona la conversión de Office a PDF. Los demás puentes de renderer describen el renderizado de HTML, no la entrada de Office. Si la fuente es DOCX/XLSX/ODT, esta es la opción.

Migrar desde una biblioteca de PDF heredada

Por su propósito declarado, nextpdf/compat-legacy es una capa de compatibilidad para bases de código escritas para una biblioteca de PDF heredada. Permite conectar los puntos de llamada existentes con NextPDF antes de reescribirlos. Conviene tratarlo como una ayuda de migración con una eliminación planificada, no como una dependencia de runtime permanente. El código nuevo llama directamente a nextpdf/core (o a la integración con el framework correspondiente).

Ejecutar en PHP 8.1 o 7.4

Cada paquete del ecosistema declara PHP >=8.4 <9.0. nextpdf/backport-builder existe precisamente para esta restricción: su propósito declarado es un pipeline de downgrade con Rector que construye un artefacto PHP 8.1+ (y un target 7.4). Es una herramienta de compilación, no una dependencia de runtime de la aplicación. Ejecutar el builder para producir el motor con backport y luego desplegar ese motor.

Un llamador que no es de PHP o un agente de IA

nextpdf/server (NextPDF Connect) expone el motor a través de una API REST, un servicio gRPC y el Model Context Protocol. Conviene elegirlo cuando el llamador sea remoto, esté en otro lenguaje o sea un sistema de IA que consume un endpoint de herramienta en lugar de una biblioteca PHP. Una aplicación PHP en el mismo proceso debería usar nextpdf/core o una integración con un framework en vez de asumir el coste de un salto de red.

Usar más de una integración a la vez

Una integración con un framework y un puente de renderer operan en capas distintas, así que se pueden instalar ambos. La integración con el framework se encarga del cableado del contenedor y de la respuesta HTTP; el puente de renderer se encarga del backend de renderizado. Al resolver un conjunto combinado de dependencias, comprobar qué versiones de nextpdf/core acepta cada paquete. Para eso, la referencia de restricción del core en el índice del cookbook de integraciones es la fuente canónica. Las recipes por combinación están en los repositorios correspondientes y se enlazan desde ese índice.

Véase también

Cookbook de integraciones — referencia de paquetes y de restricciones del core, y el índice de enlaces de recipes.
Convenciones de recipes — el contrato que sigue cada recipe ejecutable.