Cookbook delle integrazioni

Il core di NextPDF genera PDF 2.0 da PHP. I nove pacchetti di integrazione dell’ecosistema collegano quel motore a un framework, a un backend di rendering, a una codebase legacy, a una pipeline di build o a un servizio di rete. Questa pagina spiega a cosa serve ciascuna integrazione, riporta il nome del pacchetto e il relativo vincolo di versione del core (letti direttamente dal composer.json di ogni pacchetto) e rimanda alla ricetta quickstart di ciascuna integrazione.

Questa pagina è un indice, quindi non formula alcuna affermazione sul comportamento di alcuna integrazione. Le ricette di ciascuna integrazione appartengono al repository dell’integrazione stessa e l’aggregatore le pubblica in questo sito. Per una raccomandazione basata sul caso d’uso, vedere Scegliere un’integrazione. Per il contratto seguito da ogni ricetta eseguibile, vedere Convenzioni delle ricette.

Le cinque tipologie di integrazione

I nove pacchetti rientrano in cinque tipologie. La tipologia indica il genere di problema che l’integrazione risolve.

• Le integrazioni framework collegano NextPDF al service container e al ciclo di vita delle richieste di un framework applicativo: nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter. Si installa una di queste integrazioni, si risolve un servizio e si restituisce una risposta PDF.
• I renderer bridge delegano il passaggio da HTML a PDF o da Office a PDF a un backend di rendering esterno anziché alla pipeline in-process: nextpdf/artisan (Chrome headless tramite il Chrome DevTools Protocol), nextpdf/gotenberg (un microservizio Gotenberg), nextpdf/cloudflare (Cloudflare Browser Rendering all’edge).
• Uno shim di compatibilità consente a una codebase scritta per una libreria PDF legacy di chiamare NextPDF senza una riscrittura: nextpdf/compat-legacy.
• Uno strumento di build produce un backport PHP 8.1 / 7.4 di NextPDF per i runtime che non possono eseguire 8.4: nextpdf/backport-builder.
• Un servizio di rete espone NextPDF tramite REST, gRPC e il Model Context Protocol a sistemi di IA e chiamanti remoti: nextpdf/server (distribuito come NextPDF Connect).

I renderer bridge che usano HTTP (nextpdf/gotenberg, nextpdf/cloudflare e il percorso del client HTTP in nextpdf/laravel) dipendono da un client HTTP PSR-18 fornito dall’applicazione host. Un client PSR-18 solleva un’eccezione client tipizzata solo quando non riesce affatto a inviare la richiesta, come stabilisce la clausola di riferimento PSR-18 §4. Una risposta HTTP 4xx o 5xx è un normale valore di ritorno anziché un’eccezione, come stabilisce la stessa clausola PSR-18 §4. Le ricette che chiamano un renderer remoto gestiscono l’errore di trasporto e lo stato di risposta non riuscita come due casi distinti.

Riferimento dei pacchetti e dei vincoli di core

Ogni valore riportato di seguito viene letto dal composer.json del pacchetto indicato (la fonte autorevole). Il vincolo di core è il requisito nextpdf/core dichiarato dal pacchetto. nextpdf/backport-builder non dichiara alcun requisito nextpdf/core perché trasforma il sorgente del motore anziché dipendere dal motore a runtime.

Integrazione	Pacchetto	Tipologia	Vincolo di core	Ricetta
Laravel	nextpdf/laravel	Framework	^3.0 || ^5.2	Quickstart di Laravel
Symfony	nextpdf/symfony	Framework	^3.0 || ^5.2	Quickstart di Symfony
CodeIgniter 4	nextpdf/codeigniter	Framework	^3.0 || ^5.2	Quickstart di CodeIgniter
Artisan (Chrome)	nextpdf/artisan	Renderer bridge	^3.0 || ^5.2	Quickstart di Artisan
Gotenberg	nextpdf/gotenberg	Renderer bridge	^3.0	Quickstart di Gotenberg
Cloudflare	nextpdf/cloudflare	Renderer bridge	^3.0	Quickstart di Cloudflare
Compat (legacy)	nextpdf/compat-legacy	Shim di compatibilità	^3.0	Quickstart di TCPDF-compat
Backport builder	nextpdf/backport-builder	Strumento di build	non applicabile	Quickstart di Backport
Connect (server)	nextpdf/server	Servizio di rete	^3.0	Quickstart di Connect

NextPDF distribuisce nextpdf/server con il nome di prodotto NextPDF Connect; le relative ricette risiedono sotto lo slug di primo livello connect. nextpdf/compat-legacy fa parte della famiglia compat; le sue ricette risiedono sotto lo slug tcpdf-compat, che prende il nome dalla superficie che emula.

Ogni pacchetto richiede PHP >=8.4 <9.0 per il proprio runtime. nextpdf/backport-builder esiste appositamente per produrre artefatti eseguibili su PHP 8.1 (e un target 7.4); sul runtime più vecchio viene eseguito il motore risultante dal backport, non il builder.

A cosa serve ciascuna integrazione

Integrazioni framework

• nextpdf/laravel — un service provider Laravel 12, una facade e helper per le risposte PDF. Da usare quando l’applicazione è un’app Laravel e si vuole risolvere NextPDF dal container e restituirlo come risposta HTTP senza cablaggio manuale. Ricetta: Quickstart di Laravel.
• nextpdf/symfony — un bundle Symfony 7 con servizi di dependency injection e helper per le risposte PDF. Da usare quando l’applicazione è un’app Symfony; il bundle registra il motore come servizio e si integra con le risposte symfony/http-foundation. Ricetta: Quickstart di Symfony.
• nextpdf/codeigniter — un servizio CodeIgniter 4, un wrapper di libreria e helper per le risposte PDF. Da usare quando l’applicazione è un’app CodeIgniter 4 e si vuole rendere NextPDF disponibile tramite il service locator del framework. Ricetta: Quickstart di CodeIgniter.

Renderer bridge

• nextpdf/artisan — un renderer Chrome headless tramite il Chrome DevTools Protocol. Da usare quando un documento richiede il motore CSS di un browser per una fedeltà di impaginazione che la pipeline HTML in-process non mira a raggiungere, ed è possibile eseguire un processo Chrome vicino all’applicazione. Ricetta: Quickstart di Artisan.
• nextpdf/gotenberg — conversione da Office a PDF e da HTML a PDF tramite un microservizio Gotenberg. Da usare quando l’input è un documento Office, oppure quando il rendering deve essere eseguito out-of-process in un servizio separato. Comunica via HTTP tramite un client PSR-18 fornito dall’host. Ricetta: Quickstart di Gotenberg.
• nextpdf/cloudflare — rendering serverless tramite la Cloudflare Browser Rendering API. Da usare quando il rendering deve essere eseguito all’edge senza dover gestire un processo browser a lunga durata. Comunica via HTTP tramite un client PSR-18 fornito dall’host. Ricetta: Quickstart di Cloudflare.

Shim di compatibilità

• nextpdf/compat-legacy — un livello di compatibilità per le codebase scritte per una libreria PDF legacy. Da usare per chiamare NextPDF dal codice esistente senza riscrivere prima i punti di chiamata; è un supporto alla migrazione, non una dipendenza permanente. Ricetta: Quickstart di TCPDF-compat.

Strumento di build

• nextpdf/backport-builder — una pipeline di downgrade basata su Rector che produce una build PHP 8.1 (e target 7.4) di NextPDF. Da usare quando un runtime non può essere portato a PHP 8.4 e serve comunque eseguire il motore su quel runtime. È infrastruttura di build; non viene aggiunta alle dipendenze di runtime di un’applicazione. Ricetta: Quickstart di Backport.

Servizio di rete

• nextpdf/server (NextPDF Connect) — espone NextPDF tramite una REST API, un servizio gRPC e il Model Context Protocol. Da usare quando i chiamanti sono remoti, usano un altro linguaggio o sono sistemi di IA che necessitano di un endpoint-strumento anziché di una libreria PHP. Ricetta: Quickstart di Connect.

Come sono organizzati gli slug delle ricette

Le ricette risiedono sotto /integrations/<integration>/<recipe>/, dove <integration> è il nome breve ricavato dalla tabella di riferimento qui sopra (le ricette di Connect risiedono invece sotto lo slug di primo livello connect). La prima ricetta pubblicata da ogni integrazione si chiama quickstart; le ricette successive usano ulteriori segmenti <recipe> sotto la stessa radice. Questo indice non formula alcuna affermazione sul comportamento di alcuna pagina di destinazione. Registra solo i fatti relativi ai pacchetti verificati dal composer.json e lo slug che occupano le ricette di ciascun repository.

Vedere anche

• Scegliere un’integrazione — una matrice decisionale che collega il caso d’uso all’integrazione.
• Convenzioni delle ricette — il contratto seguito da ogni ricetta eseguibile di questo cookbook.