Cookbook de integraciones

El core de NextPDF renderiza PDF 2.0 desde PHP. Los nueve paquetes de integración del ecosistema conectan ese motor con un framework, un backend de renderizado, una base de código heredada, una pipeline de build o un servicio de red. Esta página explica para qué sirve cada integración, registra el nombre del paquete y la restricción de versión de core correspondiente (leída directamente del composer.json de cada paquete), y enlaza con la recipe de quickstart de cada integración.

Esta página es un índice; por tanto, no hace ninguna afirmación de comportamiento sobre ninguna integración. El repositorio de cada integración conserva la autoridad sobre sus recipes, y el aggregator las publica en este sitio. Para una recomendación basada en el caso de uso, consultar Elegir una integración. Para el contrato que sigue cada recipe ejecutable, consultar Convenciones de recipes.

Las cinco formas de integración

Los nueve paquetes se agrupan en cinco formas. La forma indica qué tipo de problema resuelve la integración.

Las integraciones de framework conectan NextPDF con el contenedor de servicios y el ciclo de vida de la petición de un framework de aplicación: nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter. Se instala una, se resuelve un servicio y se devuelve una respuesta PDF.
Los puentes de renderer delegan la conversión de HTML a PDF o de Office a PDF a un backend de renderizado externo, en lugar de hacerlo en la pipeline en proceso: nextpdf/artisan (headless Chrome mediante el Chrome DevTools Protocol), nextpdf/gotenberg (un microservicio Gotenberg), nextpdf/cloudflare (Cloudflare Browser Rendering en el edge).
Un shim de compatibilidad permite que una base de código escrita contra una biblioteca PDF heredada llame a NextPDF sin una reescritura: nextpdf/compat-legacy.
Una herramienta de build produce un backport de NextPDF a PHP 8.1 / 7.4 para runtimes que no pueden ejecutar 8.4: nextpdf/backport-builder.
Un servicio de red expone NextPDF mediante REST, gRPC y el Model Context Protocol para sistemas de IA y llamantes remotos: nextpdf/server (distribuido como NextPDF Connect).

Los puentes de renderer que hablan HTTP (nextpdf/gotenberg, nextpdf/cloudflare y la ruta de cliente HTTP en nextpdf/laravel) dependen de un cliente HTTP PSR-18 suministrado por la aplicación anfitriona. Un cliente PSR-18 lanza una excepción tipada de cliente solo cuando no puede enviar la petición en absoluto, como establece la cláusula aplicable PSR-18 §4. Una respuesta HTTP 4xx o 5xx es un valor de retorno normal y no una excepción, como también establece la misma cláusula PSR-18 §4. Las recipes que llaman a un renderer remoto tratan el error de transporte y el estado no exitoso como dos casos separados.

Referencia de paquete y restricción de core

Cada valor siguiente se lee del composer.json del paquete nombrado (la fuente autoritativa). La restricción de core es el requisito de nextpdf/core declarado por el paquete. nextpdf/backport-builder no declara ningún requisito de nextpdf/core porque transforma el código fuente del motor en lugar de depender del motor en tiempo de ejecución.

Integración	Paquete	Forma	Restricción de core	Recipe
Laravel	`nextpdf/laravel`	Framework	`^3.0 \|\| ^5.2`	Quickstart de Laravel
Symfony	`nextpdf/symfony`	Framework	`^3.0 \|\| ^5.2`	Quickstart de Symfony
CodeIgniter 4	`nextpdf/codeigniter`	Framework	`^3.0 \|\| ^5.2`	Quickstart de CodeIgniter
Artisan (Chrome)	`nextpdf/artisan`	Puente de renderer	`^3.0 \|\| ^5.2`	Quickstart de Artisan
Gotenberg	`nextpdf/gotenberg`	Puente de renderer	`^3.0`	Quickstart de Gotenberg
Cloudflare	`nextpdf/cloudflare`	Puente de renderer	`^3.0`	Quickstart de Cloudflare
Compat (heredado)	`nextpdf/compat-legacy`	Shim de compatibilidad	`^3.0`	Quickstart de TCPDF-compat
Backport builder	`nextpdf/backport-builder`	Herramienta de build	no aplica	Quickstart de Backport
Connect (servidor)	`nextpdf/server`	Servicio de red	`^3.0`	Quickstart de Connect

NextPDF distribuye nextpdf/server bajo el nombre de producto NextPDF Connect; sus recipes viven bajo el slug de nivel superior connect. nextpdf/compat-legacy se publica desde la familia compat; sus recipes viven bajo el slug tcpdf-compat, que toma su nombre de la superficie que emula.

Cada paquete requiere PHP >=8.4 <9.0 en su propio tiempo de ejecución. nextpdf/backport-builder existe específicamente para producir artefactos que se ejecuten en PHP 8.1 (y un target 7.4); el motor con backport resultante, y no el builder, es lo que se ejecuta en el runtime más antiguo.

Para qué sirve cada integración

Integraciones de framework

nextpdf/laravel — un service provider, una facade y helpers de respuesta PDF para Laravel 12. Usarlo cuando la aplicación sea una app Laravel y se quiera resolver NextPDF desde el contenedor y devolverlo como una respuesta HTTP sin cableado manual. Recipe: Quickstart de Laravel.
nextpdf/symfony — un bundle de Symfony 7 con servicios de inyección de dependencias y helpers de respuesta PDF. Usarlo cuando la aplicación sea una app Symfony; el bundle registra el motor como un servicio y se integra con las respuestas de symfony/http-foundation. Recipe: Quickstart de Symfony.
nextpdf/codeigniter — un servicio, un wrapper de biblioteca y helpers de respuesta PDF para CodeIgniter 4. Usarlo cuando la aplicación sea una app CodeIgniter 4 y se quiera que NextPDF esté disponible a través del localizador de servicios del framework. Recipe: Quickstart de CodeIgniter.

Puentes de renderer

nextpdf/artisan — un renderer de headless Chrome mediante el Chrome DevTools Protocol. Usarlo cuando un documento necesite el motor CSS de un navegador para una fidelidad de maquetación que la pipeline HTML en proceso no pretende ofrecer, y sea posible ejecutar un proceso de Chrome cerca de la aplicación. Recipe: Quickstart de Artisan.
nextpdf/gotenberg — conversión de Office a PDF y de HTML a PDF a través de un microservicio Gotenberg. Usarlo cuando la entrada sea un documento de Office, o cuando el renderizado deba ejecutarse fuera del proceso en un servicio separado. Se comunica por HTTP mediante un cliente PSR-18 suministrado por el anfitrión. Recipe: Quickstart de Gotenberg.
nextpdf/cloudflare — renderizado serverless a través de la Cloudflare Browser Rendering API. Usarlo cuando el renderizado deba ejecutarse en el edge sin requerir operar un proceso de navegador de larga duración. Se comunica por HTTP mediante un cliente PSR-18 suministrado por el anfitrión. Recipe: Quickstart de Cloudflare.

Shim de compatibilidad

nextpdf/compat-legacy — una capa de compatibilidad para bases de código escritas contra una biblioteca PDF heredada. Usarlo para llamar a NextPDF desde código existente sin reescribir primero los puntos de llamada; es una ayuda de migración, no una dependencia permanente. Recipe: Quickstart de TCPDF-compat.

Herramienta de build

nextpdf/backport-builder — una pipeline de downgrade basada en Rector que produce un build de NextPDF a PHP 8.1 (y un target 7.4). Usarlo cuando un runtime no pueda moverse a PHP 8.4 y aun así se necesite el motor en ese entorno. Es infraestructura de build; no se añade a las dependencias de runtime de una aplicación. Recipe: Quickstart de Backport.

Servicio de red

nextpdf/server (NextPDF Connect) — expone NextPDF mediante una API REST, un servicio gRPC y el Model Context Protocol. Usarlo cuando los llamantes sean remotos, estén en otro lenguaje o sean sistemas de IA que necesiten un endpoint de herramienta en lugar de una biblioteca PHP. Recipe: Quickstart de Connect.

Cómo se organizan los slugs de recipes

Las recipes viven bajo /integrations/<integration>/<recipe>/, donde <integration> es el nombre corto de la tabla de referencia de arriba (las recipes de Connect, en cambio, viven bajo el slug de nivel superior connect). La primera recipe que publica cada integración se llama quickstart; las recipes adicionales usan otros segmentos <recipe> bajo la misma raíz. Este índice no hace ninguna afirmación de comportamiento sobre ninguna página de destino. Solo registra los hechos del paquete verificados desde composer.json y el slug que ocupan las recipes de cada repositorio.

Véase también

Elegir una integración — una matriz de decisión que mapea casos de uso a integraciones.
Convenciones de recipes — el contrato que sigue cada recipe ejecutable de este cookbook.