Scegliere il percorso più adatto

In breve

NextPDF offre diversi punti di accesso. Quello più adatto dipende da dove viene eseguito il codice e dal tipo di output necessario. Questa pagina chiarisce tre scelte: quale distribuzione installare, quale renderer HTML utilizzare e quando un carico di lavoro richiede il livello Pro o Enterprise.

Leggere la sezione che risponde alla propria domanda oppure andare direttamente al riepilogo delle decisioni finale.

Scegliere una distribuzione

Partire dal modo in cui l’applicazione invoca il motore. La prima riga che corrisponde alla propria situazione indica la scelta corretta.

Situazione	Installazione	Perché
Un semplice progetto PHP, una libreria o uno strumento CLI	NextPDF core (nextpdf/core)	Solo il motore. Non presuppone alcun framework e non esegue alcun servizio.
Un’applicazione Laravel, Symfony o CodeIgniter	L’integrazione del framework corrispondente	Si ottengono binding del container, helper per le response e job di coda oltre al core.
Un servizio non PHP, un agente o un altro runtime che deve richiamare il motore tramite rete	NextPDF Server (nextpdf/server)	Un unico servizio espone il motore tramite MCP, REST e gRPC.
Codice Python che deve ottenere PDF da un NextPDF Server	L’SDK Python (pip install nextpdf)	Un client tipizzato per un server già in esecuzione. Non incorpora il motore.

Due aspetti generano spesso confusione:

• Un’integrazione con framework include il core. Non occorre installarli separatamente. L’adapter dichiara e risolve nextpdf/core automaticamente.
• L’SDK Python è un client, non un motore. Necessita di un endpoint NextPDF Server con cui comunicare. La generazione del PDF avviene in PHP sul lato server.

Libreria o servizio?

Se l’applicazione PHP può usare direttamente la libreria, preferire il core o un’integrazione con framework. In questo modo si esegue un processo in meno e si ottiene la latenza più bassa. Optare per il server quando il motore è richiesto da un componente non PHP oppure quando si desidera un unico servizio di rendering condiviso tra più chiamanti.

Scegliere un renderer HTML

NextPDF può eseguire il rendering da HTML a PDF in quattro modi. La pipeline integrata copre la maggior parte dei documenti senza configurazione aggiuntiva. I tre pacchetti renderer servono quando occorre un layout di livello browser o si vuole utilizzare un servizio esistente.

Renderer	Pacchetto	Dove viene eseguito	Quando sceglierlo
Integrato writeHtml()	nextpdf/core	In-process, PHP puro	Si desidera un sottoinsieme supportato di HTML e CSS senza browser e senza chiamate di rete.
Artisan	nextpdf/artisan	Chrome headless sull’host	Occorre il layout completo di Chrome — flexbox, grid, selettori complessi, web font — con testo selezionabile.
Cloudflare	nextpdf/cloudflare	Cloudflare Browser Rendering all’edge	Il rendering deve avvenire all’edge oppure si desidera tenere i processi del browser fuori dai propri host.
Gotenberg	nextpdf/gotenberg	Un servizio Gotenberg gestito autonomamente	Si convertono documenti Office (DOCX, XLSX) o HTML tramite un deployment Gotenberg esistente.

Come leggere la tabella:

• Optare prima per la pipeline integrata. È il percorso più rapido e non ha dipendenze esterne. Prima di fare affidamento su una proprietà, verificarla nella matrice di supporto CSS.
• Passare ad Artisan quando un layout supera il sottoinsieme supportato e il rendering deve rimanere sulla propria infrastruttura. Artisan avvia un processo Chrome, quindi è necessario pianificarne il ciclo di vita.
• Passare a Cloudflare quando si desidera la stessa fedeltà del browser ma si preferisce eseguire il rendering all’edge invece di eseguire browser in locale.
• Passare a Gotenberg per la conversione di documenti Office oppure quando si esegue già Gotenberg e si vuole che NextPDF lo piloti.

I renderer ampliano la superficie di attacco

Per impostazione predefinita, la pipeline integrata non esegue script e non recupera risorse remote. Artisan, Cloudflare e Gotenberg eseguono ciascuno il rendering tramite un browser o un servizio di rete. Considerare l’HTML come non attendibile e leggere la pagina di sicurezza e operazioni di ciascun pacchetto prima di fornire input influenzato dall’utente.

Quando servono Pro o Enterprise

Il motore core genera PDF, ne esegue il rendering e li analizza gratuitamente, senza richiedere una licenza. NextPDF Pro e NextPDF Enterprise sono i due livelli con licenza del pacchetto nextpdf/premium. Installarlo aggiunge funzionalità e non modifica alcuna API del core.

Cosa occorre fare	Livello	Funzionalità
Firmare digitalmente un PDF (baseline PAdES)	Pro	Implementazioni concrete di firma con chiave software.
Produrre output PDF/A per l’archiviazione	Pro	Conformità PDF/A e profili di archiviazione.
Incorporare una fattura elettronica (Factur-X / ZUGFeRD)	Pro	Implementazioni concrete del contratto di fatturazione elettronica.
Firmare con un modulo di sicurezza hardware (HSM)	Enterprise	Operazioni con chiavi supportate da hardware.
Emettere firme elettroniche qualificate	Enterprise	Workflow di firma qualificata e superficie di conformità completa.

Due regole aiutano a mantenere corretta la scelta:

• Se l’output è costituito da PDF non firmati e non destinati all’archiviazione, il core è sufficiente. Non è necessaria alcuna licenza.
• Quando si installa nextpdf/premium, le integrazioni con i framework e il server lo rilevano automaticamente. Espongono la funzionalità aggiuntiva tramite le stesse chiavi del container e lo stesso catalogo di strumenti. L’applicazione non richiede alcuna modifica al codice per usarla.

Riepilogo delle decisioni

Distribuzione

PHP semplice → core. App con framework → l’integrazione corrispondente. Confine di rete → il server. Client Python → l’SDK Python.

Renderer HTML

Sottoinsieme supportato, nessuna dipendenza → writeHtml(). Fedeltà del browser sui propri host → Artisan. All’edge → Cloudflare. Conversione Office → Gotenberg.

Livello con licenza

PDF non firmati → core. Firma, PDF/A, fatturazione elettronica → Pro. HSM o firme qualificate → Enterprise.

Ancora indecisi?

Installare il core, eseguire Il primo PDF e aggiungere un pacchetto solo quando si presenta una esigenza concreta. È possibile modificare ognuna di queste scelte in seguito.

Vedere anche

Installare NextPDF Il comando esatto per ogni distribuzione e renderer.

Il primo PDF Generare un PDF da PHP ed eseguire il rendering da HTML a PDF.

Integrazioni La mappa completa delle estensioni, la guida alla selezione e i manuali per ciascun pacchetto.

Connect (server) Eseguire il motore come servizio di rete tramite MCP, REST e gRPC.