Imágenes

TCPDF-Next soporta la incrustación de imágenes raster y vectoriales en documentos PDF. El subsistema de imágenes reside en el módulo Graphics y se accede a través de la API fluida de Document.

Formatos soportados

Formato	Extensión	Alpha	Notas
JPEG	.jpg, .jpeg	No	Baseline y progresivo
PNG	.png	Sí	8-bit, 24-bit, 32-bit con transparencia
WebP	.webp	Sí	Con pérdida y sin pérdida
AVIF	.avif	Sí	Requiere GD o Imagick con soporte AVIF
SVG	.svg	--	Vectorial — renderizado a través de SvgParser
EPS	.eps, .ai	--	PostScript — renderizado a través de EpsParser

image()

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->image('/path/to/logo.png', 10, 10, 50, 0);   // Ancho=50mm, alto automático

Firma

image(
    string $file,             // Ruta de archivo, URL o cadena @base64
    float  $x     = '',       // Posición X ('' = X actual)
    float  $y     = '',       // Posición Y ('' = Y actual)
    float  $w     = 0,        // Ancho  (0 = automático por relación de aspecto)
    float  $h     = 0,        // Alto (0 = automático por relación de aspecto)
    string $type  = '',       // Forzar formato: 'JPEG', 'PNG', 'WebP', etc.
    mixed  $link  = '',       // URL o identificador de enlace interno
    string $align = '',       // Alineación después de la imagen: T, M, B, N
    bool   $resize    = false,
    int    $dpi       = 300,
    string $palign    = '',   // Alineación de imagen dentro de la celda: L, C, R
    bool   $fitbox    = false,
    bool   $fitonpage = false
): static

Posicionamiento y escalado

$pdf->image('/path/to/photo.jpg', 10, 60, 100, 80);      // Absoluto: 100x80mm en (10,60)
$pdf->image('/path/to/banner.png', 10, 10, 190, 0);       // Alto automático desde el ancho
$pdf->image('/path/to/portrait.jpg', 10, 10, 0, 100);     // Ancho automático desde el alto
$pdf->image('/path/to/photo.jpg', 10, 10, 80, 60, fitbox: true);    // Ajustar en caja
$pdf->image('/path/to/chart.png', 10, 10, 0, 0, fitonpage: true);   // Ajustar en página

• Posición absoluta — proporciona coordenadas explícitas $x, $y (unidad predeterminada: mm).
• Alto/ancho automático — establece una dimensión en 0; la otra se calcula a partir de la relación de aspecto.
• Ajustar dentro de caja (fitbox: true) — escala para ajustar en $w x $h preservando la relación de aspecto.
• Ajustar en página (fitonpage: true) — asegura que la imagen nunca exceda el área imprimible.

DPI y resolución

El parámetro $dpi controla el mapeo de píxeles a tamaño físico cuando tanto $w como $h son 0:

$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 150);  // Más grande en la página
$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 300);  // Más pequeño en la página

Imagen desde cadena o URL

$pdf->image('https://example.com/logo.png', 10, 10, 50, 0);           // Desde URL
$pdf->image('@' . base64_encode($imageData), 10, 10, 50, 0, 'PNG');   // Desde base64

Cuando cargas desde una cadena base64, proporciona el parámetro $type para que el analizador conozca el formato.

Imágenes con enlaces

$pdf->image('/path/to/logo.png', 10, 10, 40, 0, link: 'https://example.com');

Imágenes SVG

imageSvg() renderiza SVG como rutas vectoriales nativas de PDF — sin rasterización:

imageSvg(string $file, float $x, float $y, float $w, float $h, mixed $link = '', string $align = '', string $palign = '', mixed $border = 0): static

$pdf->imageSvg('/path/to/diagram.svg', 10, 150, 180, 100);

Imágenes EPS / PostScript

imageEps(string $file, float $x, float $y, float $w, float $h, mixed $link = '', bool $useBBox = true, string $align = '', string $palign = '', mixed $border = 0): static

$pdf->imageEps('/path/to/illustration.eps', 10, 10, 80, 60);

Ejemplo completo

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->image('/path/to/logo.png', 10, 10, 50, 0)
    ->image('/path/to/photo.jpg', 10, 60, 100, 80)
    ->imageSvg('/path/to/diagram.svg', 10, 150, 180, 100)
    ->save('output.pdf');

Consejos

• Los canales alpha de PNG se preservan completamente en la salida PDF.
• Para la mejor calidad de impresión, usa imágenes a 300 DPI o más.
• El renderizado SVG soporta la mayoría de las características estáticas; las animaciones y JavaScript se ignoran.
• Cuando incrustes muchas imágenes, considera redimensionar previamente los archivos grandes para controlar el uso de memoria.