Guida alla scelta dell'integrazione

Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 Evidence ¶ Editorial Evidence: Editorial

In sintesi

L’ecosistema NextPDF è composto da un motore di base compatto e da un insieme di pacchetti mirati — ponti per framework, due renderer HTML, un renderer edge e un server di esecuzione. Questa pagina collega i casi d’uso reali al pacchetto adatto, in base a ciò che ciascun pacchetto contiene davvero. La scelta resta una decisione basata sulle evidenze, non una scelta implicita presa da questa documentazione al posto di chi integra.

Perché è importante

Scegliere l’integrazione sbagliata comporta un costo che non emerge subito. Scegliere un renderer browser remoto quando il motore in-process avrebbe reso il documento senza problemi significa aggiungere a ogni PDF un salto di rete e una dipendenza di disponibilità. Scegliere il motore in-process per un documento che ha davvero bisogno di un motore di layout browser completo significa ottenere un file sottilmente scorretto. Il pacchetto adottato modella latenza, modalità di guasto e superficie operativa, perciò la decisione deve essere esplicita.

In breve

• Iniziare dal motore di base. Tutto il resto è un’aggiunta. Se il motore in-process rende correttamente il documento, non serve alcun pacchetto renderer.
• Il ponte per framework segue il framework, non il documento. Le integrazioni per Laravel, Symfony e CodeIgniter esistono per fornire una facade o una factory, una risposta PDF, la generazione in coda e l’auto-discovery — non cambiano ciò che il motore può rendere.
• Usare un renderer solo quando la fedeltà CSS richiede un browser. Artisan (Chrome locale) e Cloudflare (browser edge) esistono esattamente per questo; Gotenberg esiste per importare documenti Office.
• Usare Connect quando il chiamante è un servizio o un agente IA, non una chiamata PHP. Espone il motore tramite MCP, REST e gRPC con un controllo di conferma umana per le operazioni ad alto rischio.

Come lo affronta NextPDF

L’ecosistema è volutamente stratificato affinché ogni pacchetto abbia un solo compito. Il motore di base rende il PDF in-process. Un ponte per framework adatta quel motore agli idiomi di un framework. Un pacchetto renderer delega il layout HTML o Office a un motore esterno quando quello in-process non è lo strumento adatto. Connect trasforma il motore in un servizio di rete. Le responsabilità di questi pacchetti non si sovrappongono, ed è ciò che rende la decisione gestibile. Non si sceglie tra strumenti concorrenti: si compongono strumenti complementari.

La decisione si prende al meglio a partire dal caso d’uso. La tabella collega ogni scenario al pacchetto adatto e indica il compromesso che si accetta.

Caso d’uso	Pacchetto adatto	Ciò che fornisce davvero	Il compromesso che si accetta
PDF in un’app Laravel	nextpdf/laravel	Service provider con auto-discovery, facade Pdf, PdfResponse (inline/download/streaming, intestazioni OWASP), un GeneratePdfJob in coda con tries/timeout/backoff, registri bloccati Octane-safe	Una dipendenza da Laravel 12; le capacità del motore restano invariate
PDF in un’app Symfony	nextpdf/symfony	Bundle auto-registrato, PdfFactory iniettabile, PdfResponse, un handler Messenger opzionale per la generazione asincrona	Una dipendenza dal bundle Symfony 7.2; capacità invariate
PDF in un’app CodeIgniter 4	nextpdf/codeigniter	Helper service('pdf') / pdf(), una libreria Pdf che incapsula un Document usa-e-getta, un PdfResponse, un job in coda opzionale	Una dipendenza da CodeIgniter 4.6; capacità invariate
Il documento richiede CSS browser completo (flex/grid/web font) accanto all’in-process	nextpdf/artisan	Chrome headless tramite CDP, reso e poi reimportato come Form XObject affinché il testo resti selezionabile; un pool di browser	Un runtime Chrome e il suo costo in memory/process sull’host
Documenti Office (.docx, .xlsx) in PDF	nextpdf/gotenberg	Un ponte PSR-18 verso un microservizio Gotenberg con trasporto rafforzato contro l’SSRF e con IP fissato	Un servizio Gotenberg esterno e una dipendenza di rete
HTML→PDF all’edge / nessun Chrome locale	nextpdf/cloudflare	Cloudflare Browser Rendering tramite trasporto con IP fissato, con fallback opzionale su Chrome locale	Un account Cloudflare e una dipendenza di rete; il fallback richiede Artisan
Motore consumato da un servizio o da un agente IA	nextpdf/server (Connect)	Un solo motore tramite MCP (stdio), REST (OpenAPI 3.1) e gRPC; discovery dei tool tramite dipendenze soft; un controllo di conferma umana per i tool ad alto rischio	Gestire una superficie di servizio; disciplina di esecuzione deterministica

Human-factors note: Human-factors note

Sono due decisioni indipendenti, e spesso vengono confuse. Il ponte per framework è determinato dal framework già in uso — non amplia né riduce ciò che il motore rende. Il renderer è determinato dal documento. La domanda decisiva è se il motore CSS in-process sia sufficiente, oppure se il documento abbia davvero bisogno di un motore di layout browser. Si può avere bisogno di un ponte per framework senza renderer, di un renderer senza ponte, di entrambi o di nessuno dei due. Trattare le due scelte come un’unica domanda è l’errore di integrazione più comune, ed è per questo che questa pagina le separa.

Ciò che dice l’evidenza

Questa pagina è editoriale — una decisione di instradamento — ma l’instradamento è fondato su ciò che il manifest e le classi principali di ciascun pacchetto contengono davvero.

Evidence ¶ Editorial Evidence: Editorial

I ponti sono reali e paralleli. Ciascuno dichiara la propria dipendenza dal framework e l’auto-registrazione nel suo composer.json (extra.laravel.providers, extra.symfony.bundles, il Registrar di CodeIgniter). Ciascuno inoltre fornisce un PdfResponse, un binding per un documento usa-e-getta e un job in coda opzionale. Nessuno di essi aggiunge capacità di rendering — adattano lo stesso motore. I renderer sono reali e distinti. Artisan dipende da chrome-php/chrome e reimporta il PDF di Chrome come Form XObject per mantenere il testo selezionabile. Gotenberg e Cloudflare sono ponti HTTP PSR-18 con trasporti esplicitamente rafforzati contro l’SSRF e con IP fissato. Cloudflare può ripiegare su Artisan quando il Worker è irraggiungibile. Il composer.json di Connect dichiara i tre trasporti e un modello a dipendenze soft in cui i tool compaiono man mano che i loro pacchetti vengono installati, governato da un modello di rischio a quattro livelli con un controllo di conferma umana.

Il modo in cui questa pagina instrada è fondato sugli standard in questa forma: Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 afferma che i lettori dovrebbero poter determinare rapidamente se il contenuto serva al loro scopo (chunk), e Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x222 ISO/IEC/IEEE 26514:2022 §3.x222 richiede che i link e i riferimenti indichino la loro destinazione — ed è per questo che la tabella nomina il pacchetto concreto e il compromesso anziché fare un vago riferimento a «un’integrazione».

Esempio pratico

La decisione è una sequenza di domande oneste, non un confronto di funzionalità. Quanto segue risolve i casi comuni.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

La struttura è la lezione: rendering e invocazione sono assi distinti. Rispondere alle due domande insieme è il modo in cui i team finiscono con un renderer remoto di cui non avevano bisogno o con un ponte che non risolve il loro problema di fedeltà.

Equivoco comune

L’equivoco predominante è «mi serve un pacchetto renderer per generare PDF». No, non serve. Il motore di base genera il PDF in-process. I pacchetti renderer esistono solo per il caso specifico in cui è richiesto un motore di layout di livello browser oppure la sorgente è un documento Office. Quando il motore in-process produce già il file corretto, adottare un renderer per riflesso aggiunge una dipendenza a runtime e una modalità di guasto senza alcun beneficio.

L’equivoco speculare è «il ponte per framework sblocca capacità». No, non lo fa. Un ponte cambia come si chiama il motore — facade, factory, risposta, job in coda — non ciò che è in grado di produrre. Firma, PDF/A e fatture strutturate sono questioni di livello e di motore, identiche sia chiamando tramite un ponte sia chiamando direttamente.

Limiti e confini

• Questa pagina instrada; non esegue benchmark né classifiche. Indica ciò che ciascun pacchetto fornisce e il compromesso. Scegliere tra essi è una decisione da prendere in base ai propri vincoli.
• Le capacità dei pacchetti sono lette dai loro manifest e dalle loro classi principali in un dato momento. Considerare la documentazione di ciascun pacchetto come autorevole per la sua API attuale. Questa guida è la mappa, non la specifica.
• Non viene offerto né implicato alcun confronto con concorrenti. L’unico argomento è l’ecosistema NextPDF e come le sue parti si incastrano.
• Il ponte per framework e il renderer sono scelte indipendenti. Un ponte non espande le capacità del motore; un renderer non dipende da un framework.
• I renderer esterni aggiungono una dipendenza di disponibilità. Gotenberg e Cloudflare introducono una chiamata di rete e un servizio da gestire; è un compromesso esplicito, non un costo nascosto.
• Le capacità soggette a livello sono ortogonali all’integrazione. Le funzionalità commerciali sono sbloccate dal livello, non da un ponte o da un renderer; vedere il confine qui sotto.

Ecosystem packages and tiering — edition availability

Edition	Availability
Core	○ Ogni pacchetto di integrazione (ponti, Artisan, Gotenberg, Cloudflare, Connect) opera su Core ed è Apache-2.0. Adattano o espongono il motore; non limitano le funzionalità.
Pro	○ Le capacità commerciali (firma baseline PAdES, PDF/A, codici a barre avanzati) sono sbloccate dal livello e diventano poi disponibili attraverso qualsiasi integrazione, non cambiando integrazione.
Enterprise	○ Le fatture strutturate, le policy di validazione e il controllo di conferma umana di Connect per i tool ad alto rischio sono capacità di livello, anch’esse indipendenti dall’integrazione.

Documenti correlati

• La pipeline HTML — ciò che il motore CSS in-process copre, così da capire quando serve davvero un renderer browser.
• Quando non usare NextPDF — il confine esplicito sui problemi documentali per i quali il motore non è lo strumento adatto.
• Le fondamenta di PHP 8.4 — il pavimento di runtime condiviso da ogni pacchetto e ciò che il percorso di backport preserva.

Glossario

• Motore di base — nextpdf/core, il motore PDF 2.0 in-process su cui ogni altro pacchetto si fonda.
• Ponte per framework — un pacchetto di integrazione (Laravel/Symfony/CodeIgniter) che adatta il motore agli idiomi di un framework senza cambiarne le capacità.
• Pacchetto renderer — un pacchetto che delega il layout HTML o Office a un motore esterno (Artisan/Cloudflare/Gotenberg) quando il motore in-process non è lo strumento adatto.
• Form XObject — un frammento di contenuto PDF riutilizzabile; Artisan importa in questa forma una pagina resa dal browser affinché il suo testo resti selezionabile.
• NextPDF Connect — nextpdf/server, il pacchetto che espone il motore tramite MCP, REST e gRPC con una superficie di esecuzione deterministica.
• Dipendenza soft — il modello di Connect in cui i tool compaiono automaticamente man mano che i pacchetti NextPDF opzionali vengono installati, senza modifiche al codice.