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 las recipes de cada integración a medida que los repositorios de origen publican sus árboles docs/public/ y se incorporan aquí.

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. El aggregator las incorpora a este sitio y, hasta que una recipe se incorpore, el enlace correspondiente apunta a un marcador de posición. 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 [[/integrations/laravel/quickstart/]]
Symfony	`nextpdf/symfony`	Framework	`^3.0 \|\| ^5.2`	Quickstart de Symfony [[/integrations/symfony/quickstart/]]
CodeIgniter 4	`nextpdf/codeigniter`	Framework	`^3.0 \|\| ^5.2`	Quickstart de CodeIgniter [[/integrations/codeigniter/quickstart/]]
Artisan (Chrome)	`nextpdf/artisan`	Puente de renderer	`^3.0 \|\| ^5.2`	Quickstart de Artisan [[/integrations/artisan/quickstart/]]
Gotenberg	`nextpdf/gotenberg`	Puente de renderer	`^3.0`	Quickstart de Gotenberg [[/integrations/gotenberg/quickstart/]]
Cloudflare	`nextpdf/cloudflare`	Puente de renderer	`^3.0`	Quickstart de Cloudflare [[/integrations/cloudflare/quickstart/]]
Compat (heredado)	`nextpdf/compat-legacy`	Shim de compatibilidad	`^3.0`	Quickstart de Compat-legacy [[/integrations/compat-legacy/quickstart/]]
Backport builder	`nextpdf/backport-builder`	Herramienta de build	no aplica	Quickstart de Backport [[/integrations/backport/quickstart/]]
Connect (servidor)	`nextpdf/server`	Servicio de red	`^3.0`	Quickstart de Connect [[/integrations/connect/quickstart/]]

NextPDF distribuye nextpdf/server bajo el nombre de producto NextPDF Connect; sus recipes viven bajo el slug connect. nextpdf/compat-legacy se publica desde la familia compat; sus recipes viven bajo el slug compat-legacy.

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: [[/integrations/laravel/quickstart/]].
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: [[/integrations/symfony/quickstart/]].
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: [[/integrations/codeigniter/quickstart/]].

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: [[/integrations/artisan/quickstart/]].
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: [[/integrations/gotenberg/quickstart/]].
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: [[/integrations/cloudflare/quickstart/]].

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: [[/integrations/compat-legacy/quickstart/]].

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: [[/integrations/backport/quickstart/]].

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: [[/integrations/connect/quickstart/]].

Cómo se resuelven los enlaces de recipes

Cada marcador de posición [[…]] de arriba es una referencia anticipada a una página redactada en el propio repositorio de la integración bajo docs/public/ e incorporada a este sitio por el aggregator. Los slugs de destino siguen una única convención:

/integrations/<integration>/<recipe>/

El token <integration> es el nombre corto tomado directamente de la tabla de referencia de paquete y restricción de core de arriba; cada fila de esa tabla suministra uno de esos nombres cortos. La primera recipe que publica cada integración se llama quickstart; las recipes adicionales usan otros segmentos <recipe> bajo la misma raíz <integration>. Hasta que una página de destino se agregue, su enlace es un marcador de posición y no se resuelve. 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 ocuparán 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.