Cookbook delle integrazioni
Cookbook delle integrazioni
Sezione intitolata “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 alle ricette delle singole integrazioni man mano che vengono aggregate, quando i repository di origine pubblicano i rispettivi alberi docs/public/.
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. L’aggregatore le importa in questo sito e, finché una ricetta non viene importata, il collegamento sottostante punta a un segnaposto. 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
Sezione intitolata “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
Sezione intitolata “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 [[/integrations/laravel/quickstart/]] |
| Symfony | nextpdf/symfony | Framework | ^3.0 || ^5.2 | Quickstart di Symfony [[/integrations/symfony/quickstart/]] |
| CodeIgniter 4 | nextpdf/codeigniter | Framework | ^3.0 || ^5.2 | Quickstart di CodeIgniter [[/integrations/codeigniter/quickstart/]] |
| Artisan (Chrome) | nextpdf/artisan | Renderer bridge | ^3.0 || ^5.2 | Quickstart di Artisan [[/integrations/artisan/quickstart/]] |
| Gotenberg | nextpdf/gotenberg | Renderer bridge | ^3.0 | Quickstart di Gotenberg [[/integrations/gotenberg/quickstart/]] |
| Cloudflare | nextpdf/cloudflare | Renderer bridge | ^3.0 | Quickstart di Cloudflare [[/integrations/cloudflare/quickstart/]] |
| Compat (legacy) | nextpdf/compat-legacy | Shim di compatibilità | ^3.0 | Quickstart di Compat-legacy [[/integrations/compat-legacy/quickstart/]] |
| Backport builder | nextpdf/backport-builder | Strumento di build | non applicabile | Quickstart di Backport [[/integrations/backport/quickstart/]] |
| Connect (server) | nextpdf/server | Servizio di rete | ^3.0 | Quickstart di Connect [[/integrations/connect/quickstart/]] |
NextPDF distribuisce nextpdf/server con il nome di prodotto NextPDF Connect; le relative ricette risiedono sotto lo slug connect. nextpdf/compat-legacy fa parte della famiglia compat; le sue ricette risiedono sotto lo slug compat-legacy.
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
Sezione intitolata “A cosa serve ciascuna integrazione”Integrazioni framework
Sezione intitolata “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: [[/integrations/laravel/quickstart/]].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 rispostesymfony/http-foundation. Ricetta: [[/integrations/symfony/quickstart/]].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: [[/integrations/codeigniter/quickstart/]].
Renderer bridge
Sezione intitolata “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: [[/integrations/artisan/quickstart/]].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: [[/integrations/gotenberg/quickstart/]].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: [[/integrations/cloudflare/quickstart/]].
Shim di compatibilità
Sezione intitolata “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: [[/integrations/compat-legacy/quickstart/]].
Strumento di build
Sezione intitolata “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: [[/integrations/backport/quickstart/]].
Servizio di rete
Sezione intitolata “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: [[/integrations/connect/quickstart/]].
Come si risolvono i collegamenti delle ricette
Sezione intitolata “Come si risolvono i collegamenti delle ricette”Ogni segnaposto [[…]] riportato sopra è un riferimento in avanti a una pagina redatta nel repository dell’integrazione stessa sotto docs/public/ e importata in questo sito dall’aggregatore. Gli slug di destinazione seguono una convenzione unica:
/integrations/<integration>/<recipe>/Il token <integration> è il nome breve ricavato direttamente dalla tabella di riferimento dei pacchetti e dei vincoli di core qui sopra; ogni riga di quella tabella fornisce uno di questi nomi brevi. La prima ricetta pubblicata da ogni integrazione si chiama quickstart; le ricette successive usano ulteriori segmenti <recipe> sotto la stessa radice <integration>. Finché una pagina di destinazione non viene aggregata, il suo collegamento resta un segnaposto e non si risolve. 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 occuperanno le ricette di ciascun repository.
Vedere anche
Sezione intitolata “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.