Изображения

TCPDF-Next поддерживает встраивание растровых и векторных изображений в PDF-документы. Подсистема изображений находится в модуле Graphics и доступна через fluent API класса Document.

Поддерживаемые форматы

Формат	Расширение	Альфа	Примечания
JPEG	.jpg, .jpeg	Нет	Baseline и progressive
PNG	.png	Да	8-бит, 24-бит, 32-бит с прозрачностью
WebP	.webp	Да	Lossy и lossless
AVIF	.avif	Да	Требуется GD или Imagick с поддержкой AVIF
SVG	.svg	--	Вектор — рендерится через SvgParser
EPS	.eps, .ai	--	PostScript — рендерится через EpsParser

image()

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->image('/path/to/logo.png', 10, 10, 50, 0);   // Ширина=50мм, автоматическая высота

Сигнатура

image(
    string $file,             // Путь к файлу, URL или @base64-строка
    float  $x     = '',       // Позиция X ('' = текущая X)
    float  $y     = '',       // Позиция Y ('' = текущая Y)
    float  $w     = 0,        // Ширина  (0 = авто по соотношению сторон)
    float  $h     = 0,        // Высота (0 = авто по соотношению сторон)
    string $type  = '',       // Форсировать формат: 'JPEG', 'PNG', 'WebP' и т.д.
    mixed  $link  = '',       // URL или идентификатор внутренней ссылки
    string $align = '',       // Выравнивание после изображения: T, M, B, N
    bool   $resize    = false,
    int    $dpi       = 300,
    string $palign    = '',   // Выравнивание изображения внутри ячейки: L, C, R
    bool   $fitbox    = false,
    bool   $fitonpage = false
): static

Позиционирование и масштабирование

$pdf->image('/path/to/photo.jpg', 10, 60, 100, 80);      // Абсолютно: 100x80мм в (10,60)
$pdf->image('/path/to/banner.png', 10, 10, 190, 0);       // Автовысота из ширины
$pdf->image('/path/to/portrait.jpg', 10, 10, 0, 100);     // Автоширина из высоты
$pdf->image('/path/to/photo.jpg', 10, 10, 80, 60, fitbox: true);    // Вписать в рамку
$pdf->image('/path/to/chart.png', 10, 10, 0, 0, fitonpage: true);   // Вписать на страницу

• Абсолютная позиция — укажите явные координаты $x, $y (единица по умолчанию: мм).
• Авто высота/ширина — установите одно измерение в 0; другое рассчитывается из соотношения сторон.
• Вписать в рамку (fitbox: true) — масштабирование для вписывания в $w x $h с сохранением пропорций.
• Вписать на страницу (fitonpage: true) — гарантировать, что изображение не превысит область печати.

DPI и разрешение

Параметр $dpi управляет преобразованием пикселей в физический размер, когда и $w, и $h равны 0:

$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 150);  // Крупнее на странице
$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 300);  // Мельче на странице

Изображение из строки или URL

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

При загрузке из base64-строки укажите параметр $type, чтобы парсер знал формат.

Изображения со ссылками

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

SVG-изображения

imageSvg() рендерит SVG как нативные PDF-векторные пути — без растеризации:

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

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

Полный пример

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

Советы

• Альфа-каналы PNG полностью сохраняются в PDF-выводе.
• Для лучшего качества печати используйте изображения с разрешением 300 DPI и выше.
• SVG-рендеринг поддерживает большинство статических функций; анимации и JavaScript игнорируются.
• При встраивании множества изображений рассмотрите предварительное уменьшение больших файлов для контроля потребления памяти.