Imagens

O TCPDF-Next suporta incorporação de imagens raster e vetoriais em documentos PDF. O subsistema de imagens reside no módulo Graphics e é acessado através da API fluente do Document.

Formatos Suportados

Formato	Extensão	Alpha	Notas
JPEG	.jpg, .jpeg	Não	Baseline e progressivo
PNG	.png	Sim	8-bit, 24-bit, 32-bit com transparência
WebP	.webp	Sim	Com e sem perda
AVIF	.avif	Sim	Requer GD ou Imagick com suporte AVIF
SVG	.svg	--	Vetorial — renderizado via SvgParser
EPS	.eps, .ai	--	PostScript — renderizado via EpsParser

image()

use Yeeefang\TcpdfNext\Core\Document;

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

Assinatura

image(
    string $file,             // Caminho do arquivo, URL ou string @base64
    float  $x     = '',       // Posição X ('' = X atual)
    float  $y     = '',       // Posição Y ('' = Y atual)
    float  $w     = 0,        // Largura  (0 = auto pela proporção)
    float  $h     = 0,        // Altura (0 = auto pela proporção)
    string $type  = '',       // Forçar formato: 'JPEG', 'PNG', 'WebP', etc.
    mixed  $link  = '',       // URL ou identificador de link interno
    string $align = '',       // Alinhamento após imagem: T, M, B, N
    bool   $resize    = false,
    int    $dpi       = 300,
    string $palign    = '',   // Alinhamento da imagem na célula: L, C, R
    bool   $fitbox    = false,
    bool   $fitonpage = false
): static

Posicionamento e Escala

$pdf->image('/path/to/photo.jpg', 10, 60, 100, 80);      // Absoluto: 100x80mm em (10,60)
$pdf->image('/path/to/banner.png', 10, 10, 190, 0);       // Altura automática pela largura
$pdf->image('/path/to/portrait.jpg', 10, 10, 0, 100);     // Largura automática pela altura
$pdf->image('/path/to/photo.jpg', 10, 10, 80, 60, fitbox: true);    // Caber na caixa
$pdf->image('/path/to/chart.png', 10, 10, 0, 0, fitonpage: true);   // Caber na página

• Posição absoluta — forneça coordenadas $x, $y explícitas (unidade padrão: mm).
• Altura/largura automática — defina uma dimensão como 0; a outra é calculada pela proporção.
• Caber na caixa (fitbox: true) — escala para caber em $w x $h preservando a proporção.
• Caber na página (fitonpage: true) — garante que a imagem nunca exceda a área imprimível.

DPI e Resolução

O parâmetro $dpi controla o mapeamento pixel-para-tamanho-físico quando $w e $h são ambos 0:

$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 150);  // Maior na página
$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 300);  // Menor na página

Imagem a Partir de String ou URL

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

Ao carregar de uma string base64, forneça o parâmetro $type para que o analisador conheça o formato.

Imagens com Links

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

Imagens SVG

imageSvg() renderiza SVG como caminhos vetoriais nativos do PDF — sem rasterização:

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);

Imagens 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);

Exemplo 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');

Dicas

• Canais alpha de PNG são totalmente preservados na saída PDF.
• Para melhor qualidade de impressão, use imagens em 300 DPI ou superior.
• A renderização SVG suporta a maioria das funcionalidades estáticas; animações e JavaScript são ignorados.
• Ao incorporar muitas imagens, considere redimensionar previamente arquivos grandes para controlar o uso de memória.