Intégrer des images avec NextPDF Connect

En bref

Intègre une image dans un PDF avec NextPDF Connect. La source peut être un chemin de fichier lisible par le serveur ou un data URI base64 en ligne. Les outils sont create_pdf, add_image et output_pdf, tous disponibles dans Core. Une image est dessinée comme un objet image XObject peint par l’opérateur Do (ISO 32000-2 §8.9).

Installation

composer require nextpdf/server

Associe un transport. Les formats raster pris en charge sont PNG, JPEG et GIF.

Vue d’ensemble conceptuelle

add_image reçoit une source et la résout dans un ordre fixe :

Data URI — une chaîne qui commence par data:. NextPDF analyse le type MIME, décode la charge utile base64 dans un fichier temporaire, l’intègre, puis supprime ce fichier temporaire.
Base64 brut — une longue chaîne base64 est décodée et traitée comme du PNG.
Chemin de fichier — tout le reste est traité comme un chemin du système de fichiers que le processus serveur doit pouvoir lire.

L’image est placée en x/y, en unités utilisateur (millimètres par défaut). Si tu ne passes que width, la hauteur est calculée pour préserver le rapport d’aspect. Si tu passes à la fois width et height, l’image est mise à l’échelle à ces dimensions exactes. L’objet intégré est un objet externe peint dans le contenu de la page (ISO 32000-2 §8.8).

Surface d’API

Outil	Rôle	Niveau de risque
`create_pdf`	Ouvrir la session	Sûr
`add_image`	Intégrer une image à partir d’un chemin ou d’un data URI	Prudence
`output_pdf`	Rendre et renvoyer le PDF	Approbation requise / Examen (base64)

Le catalogue d’outils est la référence. Les outils dont tu disposes dépendent du palier installé.

Exemple de code — Démarrage rapide

create_pdf (A4 portrait, titre) → document_id.
add_image avec source renseigné par un chemin absolu, x, y, width.
add_image avec source renseigné par un URI data:image/png;base64,... et des valeurs explicites de width et height.
output_pdf → base64.

Exemple de code — Production

Utilise un data URI pour une image générée en mémoire par l’hôte, par exemple le rendu d’un graphique ou une capture d’écran. Utilise un chemin de fichier pour une ressource déjà présente sur le serveur. Utilise toujours des chemins absolus. Un chemin relatif est résolu par rapport au répertoire de travail du serveur, qui n’est généralement pas celui de l’hôte. Avant de continuer, confirme que la réponse de add_image indique que l’image se trouve sur la page attendue.

Cas limites & pièges

Chemin introuvable. Un chemin de fichier manquant renvoie une erreur « image introuvable ».
Format non pris en charge. SVG, BMP et WebP sont rejetés. Convertis d’abord l’image.
Base64 / data URI mal formé. Une charge utile incorrecte ou un data URI dépourvu du séparateur virgule renvoie une erreur de décodage.
Image surdimensionnée. Une image plus grande que la page est rognée aux bords, et non rejetée. Calcule width/height à partir des dimensions de la page, marges déduites (A4 portrait fait 210×297 mm).

Performances

La taille de sortie varie selon le contenu de l’image. Deux petites images pèsent généralement 10–50 Ko. Le budget d’intégration des images est plus large que celui du texte seul. Le profil est structural.

Notes de sécurité

Le mode chemin de fichier lit dans le système de fichiers du serveur avec les privilèges du processus serveur. Restreins les chemins que l’hôte peut transmettre. Ne laisse pas des appelants non fiables faire pointer source vers des fichiers serveur arbitraires. Le mode base64 transporte les octets en ligne, ce qui évite toute exposition d’un chemin serveur.

Conformité

Énoncé	Spécification	Clause	reference_id
Une image est un objet image XObject peint par `Do`.	ISO 32000-2	§8.9
Les images sont des objets externes peints dans le contenu de la page.	ISO 32000-2	§8.8

Contexte commercial

Sans objet : tous les outils sont Core.

Disponibilité par transport

Transport	Disponible	Notes
MCP (stdio)	Oui	Les charges utiles base64 volumineuses gonflent la trame stdio.
REST	Oui	Préfère le multipart ou un chemin serveur pour les actifs volumineux.
gRPC	Oui	Appel unaire ; les limites de taille de message s’appliquent au base64 en ligne.

Niveau de risque HITL

create_pdf est Safe, add_image est Caution, et output_pdf est Approval Required, rétrogradé à Review en mode base64. La lecture en mode chemin s’effectue côté serveur et n’est pas contrôlée séparément ; restreins-la donc au niveau de la couche de politique (niveaux de risque HITL).

Enveloppe JSON du contrôle de confirmation

Pour une sortie base64 :

{ "allowed": true }