Images

Images

$page->image() places a raster (PNG, JPEG) or vector (SVG) image on the page. Images are loaded once per document and reused across any number of placements at no extra size cost. The top-left corner of the image is anchored at (x, y) in the document unit (mm by default, Y-down).

Basic usage

use DragonOfMercy\PhpPdf\Image;

// Path string: format auto-detected, file read once and cached per document.
$page->image('logo.png', x: 20, y: 20, w: 40, h: 20);   // 40x20 mm (forced, may distort)

// Image instance: load bytes once, place multiple times or on different pages.
$photo = Image::fromFile('photo.jpg');
$page->image($photo, x: 20, y: 60, w: 80);              // h derived from aspect ratio

// From in-memory bytes (PNG, JPEG, or SVG string).
$icon = Image::fromBytes(file_get_contents('icon.png'));
$page->image($icon, x: 20, y: 100, w: 20);

// From a base64 string; data URI prefix is accepted (e.g. canvas.toDataURL() output).
$signature = Image::fromBase64($request->input('signature_png'));
$page->image($signature, x: 20, y: 130, w: 60);

// Same path used twice: embedded once in the PDF, two placements.
$page->image('logo.png', x: 150, y: 20, w: 30, h: 15);

Page::image() parameters

Parameter	Type	Description
$image	string|Image	File path or an Image instance.
x	float|null	Left edge in the document unit. Defaults to the current cursor X if omitted.
y	float|null	Top edge in the document unit. Defaults to the current cursor Y if omitted.
w	float|null	Width in the document unit. See dimension rules below.
h	float|null	Height in the document unit. See dimension rules below.
ln	NextPosition	Where the cursor lands after the image. Defaults to NextPosition::RIGHT. See Cursor flow below.

The method returns $this (the Page) for chaining.

Dimension rules

w	h	Result
provided	provided	Forced to exactly w x h. Aspect ratio may be distorted.
provided	omitted	Height derived to preserve the aspect ratio.
omitted	provided	Width derived to preserve the aspect ratio.
omitted	omitted	Intrinsic pixel size at 72 DPI: 1 pixel = 1 point ~ 0.353 mm.

Cursor flow

Like cell(), image() reads the cursor when x / y are omitted and advances it after drawing. The ln parameter controls where it lands. The default is RIGHT (unlike barcode(), which defaults to NONE), so chained images without an explicit x flow left to right.

Value	Behavior
NextPosition::RIGHT	Cursor moves to the right edge of the image (default)
NextPosition::NEWLINE	Cursor returns to the row's start X and drops below the image
NextPosition::BELOW	Cursor moves below the image, same X
NextPosition::NONE	Cursor is left untouched (stamps / overlays)

use DragonOfMercy\PhpPdf\NextPosition;

$page->setXY(20, 20);
$page->image('a.png', w: 30, h: 20);                            // RIGHT (default): next image flows right
$page->image('b.png', w: 30, h: 20, ln: NextPosition::NEWLINE); // drop to a new row at the start X
$page->image('c.png', w: 30, h: 20);                            // sits on the new row

image() does not auto-page-break: when stacking images that may overflow, manage y or call $doc->addPage() yourself.

Image factories

Factory	Description
Image::fromFile(string $path)	Reads the file from disk. Format (PNG, JPEG, SVG) is auto-detected.
Image::fromBytes(string $data)	Accepts raw PNG/JPEG bytes or an inline SVG string.
Image::fromBase64(string $data)	Accepts a raw base64 string or a full data URI (data:image/png;base64,...).

All three factories return the same Image value object. It can be passed directly to $page->image() or to Cell::image() in a table.

Per-document caching

phppdf maintains an image registry per Document. A given file path or Image instance is embedded in the PDF stream only once, regardless of how many times it is placed or on how many pages. Creating multiple Image::fromFile() calls for the same path also deduplicates: the file bytes are shared.

SVG images

SVG inputs are auto-detected by magic bytes (<svg or <?xml ... <svg). They flow through the same Image::fromXxx() factories and the same $page->image() call as PNG and JPEG.

// SVG from a file.
$logo = Image::fromFile('logo.svg');
$page->image($logo, x: 20, y: 20, w: 40);

// Inline SVG string.
$icon = Image::fromBytes(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">'
    . '<path d="M12 2L2 22h20z" fill="currentColor"/>'
    . '</svg>',
);
$page->image($icon, x: 80, y: 20, w: 20);

// data URI (e.g. from a JavaScript export).
$brand = Image::fromBase64('data:image/svg+xml;base64,...');
$page->image($brand, x: 20, y: 80, w: 60);

The same four dimension rules apply. Caching works identically: one SVG embed, N placements.

See also

• Examples - see example-catalog.php
• SVG Support
• Tables