Incrustar imágenes con NextPDF Connect

Visión general

Incrustar una imagen en un PDF con NextPDF Connect. El origen puede ser una ruta de archivo legible por el servidor o un data URI base64 en línea. Las herramientas son create_pdf, add_image y output_pdf, todas Core. Una imagen se dibuja como un XObject de imagen, pintado por el operador Do (ISO 32000-2 §8.9).

Instalación

composer require nextpdf/server

Configurar un transporte. Los formatos ráster admitidos son PNG, JPEG y GIF.

Descripción conceptual

add_image recibe un source y lo resuelve en un orden fijo:

Data URI — una cadena que empieza por data:. NextPDF identifica el tipo MIME, decodifica la carga base64 en un archivo temporal, la incrusta y luego elimina el archivo temporal.
Base64 sin procesar — una cadena base64 larga se decodifica y se trata como PNG.
Ruta de archivo — cualquier otro valor se trata como una ruta del sistema de archivos que el proceso del servidor debe poder leer.

La imagen se coloca en x/y, en unidades de usuario (milímetros de forma predeterminada). Si se pasa solo width, la altura se calcula para conservar la relación de aspecto. Si se pasan tanto width como height, la imagen se escala a esas dimensiones exactas. El objeto incrustado es un objeto externo pintado en el contenido de la página (ISO 32000-2 §8.8).

Superficie de la API

Herramienta	Función	Nivel de riesgo
`create_pdf`	Abrir una sesión	Seguro
`add_image`	Incrustar una imagen desde una ruta o un data URI	Precaución
`output_pdf`	Generar y devolver el PDF	Aprobación requerida / Revisión (base64)

El catálogo de herramientas es la referencia principal. Las herramientas disponibles dependen del nivel instalado.

Ejemplo de código — Inicio rápido

create_pdf (A4 vertical, título) → document_id.
add_image con source definido como una ruta absoluta, x, y, width.
add_image con source definido como un URI data:image/png;base64,... y width y height explícitos.
output_pdf → base64.

Ejemplo de código — Producción

Usar un data URI para una imagen que el host generó en memoria, como la representación de un gráfico o una captura de pantalla. Usar una ruta de archivo para un recurso que ya esté en el servidor. Usar siempre rutas absolutas. Una ruta relativa se resuelve respecto al directorio de trabajo del servidor, que normalmente no es el del host. Antes de continuar, confirmar que la respuesta de add_image indica la imagen en la página esperada.

Casos límite y errores frecuentes

Ruta no encontrada. Una ruta de archivo inexistente devuelve un error de imagen no encontrada.
Formato no admitido. Se rechazan SVG, BMP y WebP. Convierta la imagen primero.
Base64 / data URI con formato incorrecto. Una carga mal formada, o un data URI sin separador de coma, devuelve un error de decodificación.
Imagen sobredimensionada. Una imagen mayor que la página se recorta en el borde, no se rechaza. Calcular width/height respecto a la página menos sus márgenes (A4 vertical mide 210×297 mm).

Rendimiento

El tamaño de salida aumenta según el contenido de la imagen. Dos imágenes pequeñas suelen ocupar entre 10 y 50 KB. El presupuesto para incrustar imágenes es más amplio que el de solo texto. El perfil es structural.

Notas de seguridad

El modo de ruta de archivo lee desde el sistema de archivos del servidor con los privilegios del proceso del servidor. Restringir qué rutas puede pasar el host. No permitir que invocadores no confiables apunten source a archivos arbitrarios del servidor. El modo base64 transporta los bytes en línea, por lo que evita exponer rutas del servidor.

Conformidad

Declaración	Especificación	Cláusula	reference_id
Una imagen es un XObject de imagen pintado por `Do`.	ISO 32000-2	§8.9
Las imágenes son objetos externos pintados en el contenido de la página.	ISO 32000-2	§8.8

Contexto comercial

No aplica — todas las herramientas son Core.

Disponibilidad por transporte

Transporte	Disponible	Notas
MCP (stdio)	Sí	Las cargas base64 grandes aumentan el tamaño de la trama stdio.
REST	Sí	Preferir multipart o una ruta de servidor para recursos grandes.
gRPC	Sí	Llamada unaria; los límites de tamaño de mensaje se aplican al base64 en línea.

Nivel de riesgo HITL

create_pdf es Seguro, add_image es Precaución y output_pdf es Aprobación requerida — rebajada a Revisión en modo base64. La lectura en modo de ruta se realiza del lado del servidor y no se limita por separado, así que restringirla en la capa de políticas (niveles de riesgo HITL).

Envoltorio JSON de la puerta de confirmación

Aquí, la salida base64:

{ "allowed": true }