Incorporare immagini in NextPDF Connect

In sintesi

Per incorporare un’immagine in un PDF con NextPDF Connect, usare una sorgente costituita da un percorso file leggibile dal server oppure da un data URI base64 inline. Gli strumenti coinvolti sono create_pdf, add_image e output_pdf — tutti Core. Un’immagine viene disegnata come XObject immagine, dipinta dall’operatore Do (ISO 32000-2 §8.9).

Installazione

composer require nextpdf/server

Associare quindi un trasporto. I formati raster supportati sono PNG, JPEG e GIF.

Panoramica concettuale

add_image accetta una source e la risolve secondo un ordine fisso:

Data URI — una stringa che inizia con data:. NextPDF decodifica il tipo MIME e il payload base64 in un file temporaneo, lo incorpora, quindi rimuove il file temporaneo.
Base64 grezzo — una stringa base64 lunga viene decodificata e trattata come PNG.
Percorso file — qualsiasi altra cosa viene trattata come un percorso del filesystem che il processo server deve poter leggere.

L’immagine viene posizionata alle coordinate x/y, espresse in unità utente (millimetri per impostazione predefinita). Passando solo width, l’altezza viene calcolata per preservare le proporzioni. Passando sia width sia height, l’immagine viene ridimensionata esattamente a tali dimensioni. L’oggetto incorporato è un oggetto esterno dipinto nel contenuto della pagina (ISO 32000-2 §8.8).

Superficie API

Strumento	Ruolo	Livello di rischio
`create_pdf`	Apre la sessione	Sicuro
`add_image`	Incorpora un’immagine da un percorso o da un data URI	Attenzione
`output_pdf`	Esegue il rendering e restituisce il PDF	Approvazione richiesta / Revisione (base64)

Il catalogo degli strumenti è il riferimento principale. Gli strumenti disponibili dipendono dal livello installato.

Esempio di codice — Avvio rapido

create_pdf (A4 verticale, titolo) → document_id.
add_image con source impostata su un percorso assoluto, x, y, width.
add_image con source impostata su un URI data:image/png;base64,... e con width e height espliciti.
output_pdf → base64.

Esempio di codice — Produzione

Usare un data URI per un’immagine generata in memoria dall’host, ad esempio il rendering di un grafico o uno screenshot. Usare un percorso file per una risorsa già presente sul server. Usare sempre percorsi assoluti. Un percorso relativo viene risolto rispetto alla directory di lavoro del server, che di solito non coincide con quella dell’host. Prima di proseguire, verificare che la risposta di add_image indichi che l’immagine è stata inserita nella pagina prevista.

Casi limite e insidie

Percorso non trovato. Un percorso file mancante restituisce un errore di immagine non trovata.
Formato non supportato. SVG, BMP e WebP vengono rifiutati. Convertire prima l’immagine.
Base64 / data URI malformato. Un payload errato o un data URI privo del separatore virgola restituisce un errore di decodifica.
Immagine sovradimensionata. Un’immagine più grande della pagina viene ritagliata al bordo, non rifiutata. Calcolare width/height rispetto alla pagina al netto dei suoi margini (l’A4 verticale è 210×297 mm).

Prestazioni

La dimensione dell’output cresce in base al contenuto dell’immagine. Due immagini piccole occupano in genere 10–50 KB. Il budget per l’incorporamento delle immagini è più ampio di quello per il solo testo. Il profilo è structural.

Note sulla sicurezza

La modalità percorso file legge dal filesystem del server con i privilegi del processo server. Limitare i percorsi che l’host può passare. Non consentire a chiamanti non attendibili di puntare source a file arbitrari del server. La modalità base64 trasporta i byte inline, evitando così l’esposizione dei percorsi del server.

Conformità

Affermazione	Specifica	Clausola	reference_id
Un’immagine è un XObject immagine dipinto da `Do`.	ISO 32000-2	§8.9
Le immagini sono oggetti esterni dipinti nel contenuto della pagina.	ISO 32000-2	§8.8

Contesto commerciale

Non applicabile — tutti gli strumenti sono Core.

Disponibilità per trasporto

Trasporto	Disponibile	Note
MCP (stdio)	Sì	Payload base64 di grandi dimensioni aumentano la dimensione del frame stdio.
REST	Sì	Per risorse di grandi dimensioni, preferire multipart o un percorso del server.
gRPC	Sì	Unario; i limiti di dimensione dei messaggi si applicano al base64 inline.

Livello di rischio HITL

create_pdf è Sicuro, add_image è Attenzione e output_pdf è Approvazione richiesta — declassato a Revisione in modalità base64. La lettura in modalità percorso avviene lato server e non è soggetta a un controllo separato; va quindi limitata a livello di policy (livelli di rischio HITL).

Envelope JSON del gate di conferma

Output base64 in questo punto:

{ "allowed": true }