Generare il primo PDF con NextPDF Connect

In sintesi

Questa ricetta mostra il percorso più breve da una sessione vuota a un PDF generato con NextPDF Connect. Si crea un documento A4 di una sola pagina, si aggiungono un titolo e un sottotitolo, quindi si restituisce il file in base64. Tre strumenti Core svolgono tutto il lavoro: create_pdf, add_text e output_pdf. Non servono font, immagini o livelli con licenza.

Un trasporto Connect trasmette ogni chiamata di strumento come richiesta e restituisce il risultato dello strumento come risposta. Il livello di trasporto è indipendente dall’esito restituito dallo strumento (PSR-18 §p2).

Installazione

Installare NextPDF Server e associare un trasporto:

composer require nextpdf/server

Eseguire il server nel trasporto atteso dall’host: Model Context Protocol su stdio, REST o gRPC. Vedere Disponibilità dei trasporti più sotto. Gli strumenti di questa ricetta sono strumenti Core. Sono forniti con il server, quindi non serve alcun pacchetto Pro o Enterprise.

Panoramica concettuale

Una sessione Connect è un archivio di documenti lato server, indicizzato da un document_id. create_pdf apre una sessione e restituisce l’ID. Ogni chiamata di strumento successiva fa riferimento a quell’ID. Il documento inizia con una pagina vuota. L’albero delle pagine è la struttura attraverso cui un lettore raggiunge ogni pagina (ISO 32000-2 §7.7.3). output_pdf esegue il rendering della sessione in un PDF. Per impostazione predefinita, poi distrugge la sessione per liberare memoria.

Quando si chiama add_text senza un x o y esplicito, il testo viene posizionato automaticamente: parte dal cursore corrente e il cursore avanza dopo ogni chiamata.

Superficie API

Il registro degli strumenti risolve gli strumenti seguenti all’avvio del server. I nomi sono quelli di protocollo del registro. Il riferimento canonico è il catalogo degli strumenti unificato. Gli strumenti disponibili dipendono dal livello installato, ma questi tre sono sempre presenti in Core.

Strumento	Ruolo	Livello di rischio
`create_pdf`	Apre una sessione di documento	Sicuro
`add_text`	Scrive testo nel documento	Cautela
`output_pdf`	Esegue il rendering e restituisce il PDF	Approvazione richiesta (modalità file) / Revisione (base64)

Esempio di codice — Avvio rapido

L’host effettua tre chiamate di strumento. In termini operativi:

Chiamare create_pdf con page_size: "A4", orientation: "portrait" e il titolo e l’autore del documento. Il server restituisce un document_id.
Chiamare add_text con quel document_id, il testo del titolo, un font_size grande, width: 0 (l’intera larghezza del contenuto) e alignment: "center".
Chiamare output_pdf con il document_id. Senza file_path, il server restituisce il PDF in base64 e distrugge la sessione.

Ecco un oggetto minimo di argomenti per create_pdf:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

La risposta contiene il document_id, il numero di pagine e la geometria della pagina. Trattare l’ID come un valore opaco, senza attribuirgli alcun significato.

Esempio di codice — Produzione

In produzione, ogni risposta va verificata prima della chiamata successiva. Non riutilizzare mai un document_id dopo che output_pdf ha distrutto la sessione.

create_pdf — verificare che la risposta contenga un document_id. Se il server restituisce l’errore di limite di sessioni, rilasciare le sessioni inutilizzate e riprovare.
add_text (titolo) — verificare che la risposta contenga una position.
add_text (sottotitolo) — usare un font_size più piccolo; il cursore prosegue sotto il titolo.
output_pdf — leggere il campo base64 e decodificarlo in byte. Il flag destroyed conferma che la sessione è scomparsa.

Il file viene restituito inline (modalità base64), quindi non c’è alcun effetto collaterale sul file system né alcun gate di approvazione umana — vedere Livello di rischio HITL.

Casi limite e insidie

Sessione distrutta. Dopo l’esecuzione di output_pdf con il valore predefinito destroy: true, il document_id non è più valido. Qualsiasi chiamata successiva su quel valore restituisce un errore di documento sconosciuto. Creare invece una nuova sessione.
Dimensione di pagina sconosciuta. Il server rifiuta un page_size non riconosciuto e restituisce un errore chiaro. Usare una dimensione documentata (A3, A4, A5, A6, Letter, Legal, Tabloid).
Testo vuoto. Un text vuoto produce una voce a larghezza zero, non un errore. Controllare l’input prima della chiamata.
Limite di sessioni. L’archivio in memoria limita il numero di sessioni eseguibili contemporaneamente. Rilasciare le sessioni tempestivamente con output_pdf.

Prestazioni

Una singola pagina di solo testo viene renderizzata ben entro il budget di pagina e l’output è di solito di 1–3 KB. Il profilo di riproducibilità a doppio rendering per questa ricetta è structural. Il PDF contiene un /ID nel trailer e marche temporali che cambiano da un’esecuzione all’altra, quindi un confronto strutturale (normalizzato) è l’approccio corretto.

Note di sicurezza

Il percorso base64 non ha effetti collaterali sul file system. Il percorso di output su file ne ha uno ed è protetto da gate — vedere la sezione HITL. Trattare il base64 restituito come contenuto del documento, non come un canale affidabile. Sono esattamente i byte prodotti dagli strumenti.

Conformità

Dichiarazione	Specifica	Clausola	reference_id
Un trasporto invia una richiesta e riceve una risposta indipendentemente dal risultato.	PSR-18	§p2
Le pagine vengono raggiunte tramite l’albero delle pagine del documento.	ISO 32000-2	§7.7.3

Questa ricetta descrive come il server produce l’output. Non dichiara alcuna conformità a un profilo.

Contesto commerciale

Non applicabile — tutti e tre gli strumenti sono Core.

Disponibilità dei trasporti

Trasporto	Disponibile	Note
MCP (stdio)	Sì	Le chiamate di strumento vengono mappate su MCP `tools/call`.
REST	Sì	Ogni strumento è un’operazione REST; il risultato è il corpo della risposta.
gRPC	Sì	Ogni strumento è una chiamata unaria.

Il risultato dello strumento è lo stesso su tutti i trasporti; cambia solo il framing. Un risultato non riuscito è comunque una risposta normale, non un errore di trasporto (PSR-18 §p2).

Livello di rischio HITL

Il server colloca ogni chiamata di strumento su una scala di rischio human-in-the-loop (HITL): Sicuro (0) → Cautela (1) → Revisione (2) → Approvazione richiesta (3). create_pdf è Sicuro e add_text è Cautela. output_pdf è Approvazione richiesta, ma in modalità base64 (senza file_path) scende a Revisione e viene eseguito senza conferma umana. La scrittura su file lo mantiene ad Approvazione richiesta — vedere output-approval e il riferimento ai livelli di rischio HITL.

Envelope JSON del gate di conferma

Questa ricetta resta in modalità base64, quindi il gate di conferma restituisce l’envelope di consenso:

{ "allowed": true }

L’envelope di sfida (allowed: false, con una stringa challenge e un token monouso) è documentato in output-approval.