Scegliere un'integrazione

Scegliere un’integrazione

Questa pagina collega ogni caso d’uso all’integrazione che lo gestisce. Ogni raccomandazione deriva esclusivamente dalla descrizione del composer.json del pacchetto e dal suo scopo dichiarato, entrambi letti direttamente dal repository di origine. Quando due integrazioni si sovrappongono, la pagina indica il fattore distintivo e lascia la decisione all’utente.

Individuare la riga che corrisponde alla propria situazione e partire da lì.

Punto di partenza: di che cosa si dispone?

Si dispone di …	Da usare	Perché (scopo verificato)
Un’applicazione Laravel 12	nextpdf/laravel	Integrazione con il framework Laravel: service provider, facade e helper per le risposte PDF.
Un’applicazione Symfony 7	nextpdf/symfony	Bundle Symfony: servizi DI e helper per le risposte PDF.
Un’applicazione CodeIgniter 4	nextpdf/codeigniter	Servizi CodeIgniter 4, wrapper della libreria e helper per le risposte PDF.
Un’applicazione PHP senza framework	nextpdf/core direttamente	Non serve alcuna integrazione con un framework; il motore è una semplice libreria.
HTML che richiede un motore CSS di tipo browser ed è possibile eseguire Chrome	nextpdf/artisan	Renderer Chrome CDP per HTML che richiede un layout CSS di livello browser.
Un documento Office da convertire, ad esempio DOCX, XLSX o ODT	nextpdf/gotenberg	Conversione da Office a PDF tramite microservizio Gotenberg.
La necessità di eseguire il rendering senza alcun processo browser da gestire	nextpdf/cloudflare	Rendering serverless tramite la Cloudflare Browser Rendering API all’edge.
Codice scritto basandosi su una libreria PDF legacy	nextpdf/compat-legacy	Livello di compatibilità per librerie PDF legacy; permette di chiamare NextPDF senza riscrivere i punti di chiamata.
Un runtime bloccato su PHP 8.1 / 7.4	nextpdf/backport-builder	Pipeline di downgrade Rector che genera una versione del motore destinata a 8.1 / 7.4.
Chiamanti remoti, un altro linguaggio o un sistema di IA	nextpdf/server	NextPDF Connect: interfaccia REST, gRPC e Model Context Protocol per l’esecuzione remota.

Quando due integrazioni potrebbero essere adatte

Rendering da HTML a PDF: Artisan, Gotenberg, Cloudflare o core

Tutti e tre i bridge di rendering trasformano il markup in PDF. Differiscono per modalità operativa, non per qualità; questa differenza è quindi il criterio decisivo.

• nextpdf/artisan pilota Chrome in modalità headless tramite il Chrome DevTools Protocol. Richiede un processo Chrome raggiungibile dall’applicazione. È la scelta indicata quando tale processo può essere gestito e il documento richiede un motore CSS di tipo browser.
• nextpdf/gotenberg chiama tramite HTTP un microservizio Gotenberg esterno al processo. È la scelta indicata quando il rendering deve essere isolato in un servizio dedicato oppure quando l’input è un documento Office. Gotenberg è l’unico dei tre il cui scopo dichiarato comprende la conversione da Office a PDF.
• nextpdf/cloudflare chiama la Cloudflare Browser Rendering API. È la scelta indicata quando si desidera un rendering edge/serverless senza alcun processo browser da eseguire o aggiornare.
• La pipeline HTML del core NextPDF in-process non richiede nessuno dei precedenti. Usare un bridge di rendering solo quando la pipeline in-process non può raggiungere la fedeltà di layout o l’isolamento di processo richiesti dal documento. Un bridge è una scelta deliberata per delegare quel passaggio, non il percorso predefinito.

I due bridge HTTP (nextpdf/gotenberg, nextpdf/cloudflare) richiedono un client HTTP PSR-18 fornito dall’host. Le relative ricette trattano un errore di trasporto e uno stato HTTP non di successo come due esiti distinti.

Convertire un documento Office

nextpdf/gotenberg è l’integrazione la cui descrizione verificata del composer.json menziona la conversione da Office a PDF. Gli altri bridge di rendering descrivono il rendering di HTML, non l’input Office. Se l’origine è DOCX/XLSX/ODT, questa è l’opzione corretta.

Migrare da una libreria PDF legacy

Per scopo dichiarato, nextpdf/compat-legacy è un livello di compatibilità per basi di codice scritte basandosi su una libreria PDF legacy. Consente ai punti di chiamata esistenti di raggiungere NextPDF prima di essere riscritti. Va considerato un supporto alla migrazione con rimozione pianificata, non una dipendenza di runtime permanente. Il codice nuovo chiama direttamente nextpdf/core (o la relativa integrazione con il framework).

Esecuzione su PHP 8.1 o 7.4

Ogni pacchetto dell’ecosistema dichiara PHP >=8.4 <9.0. nextpdf/backport-builder esiste proprio per questo vincolo: il suo scopo dichiarato è una pipeline di downgrade Rector che genera un artefatto per PHP 8.1+ (e una versione destinata a 7.4). È uno strumento di build, non una dipendenza di runtime dell’applicazione. Eseguire il builder per produrre il motore sottoposto a backport, quindi distribuire quel motore.

Un chiamante non PHP o un agente di IA

nextpdf/server (NextPDF Connect) espone il motore tramite un’API REST, un servizio gRPC e il Model Context Protocol. È la scelta indicata quando il chiamante è remoto, usa un altro linguaggio oppure è un sistema di IA che utilizza un endpoint tool anziché una libreria PHP. Un’applicazione PHP nello stesso processo dovrebbe usare nextpdf/core o un’integrazione con il framework anziché sostenere il costo di un hop di rete.

Usare più integrazioni insieme

Un’integrazione con il framework e un bridge di rendering operano a livelli diversi, quindi possono essere installati entrambi. L’integrazione con il framework gestisce il wiring del container e la risposta HTTP; il bridge di rendering gestisce il backend di rendering. Quando si risolve un insieme combinato di dipendenze, verificare quali versioni di nextpdf/core accetta ciascun pacchetto. A questo scopo, il riferimento ai vincoli del core nell’indice del cookbook delle integrazioni è la fonte autorevole. Le ricette specifiche per ciascuna combinazione risiedono nei rispettivi repository e sono collegate da quell’indice.

Vedere anche

• Cookbook delle integrazioni — riferimento ai pacchetti e ai vincoli del core, e indice dei collegamenti alle ricette.
• Convenzioni delle ricette — il contratto che ogni ricetta eseguibile rispetta.