Image

The Image class is a drawable item that composites a bitmap file onto the layout canvas (or inside a container cell). It preserves aspect ratio, supports alignment via gravity, and respects margin/padding/border.

Constructor

public function __construct(
    string $file,                // Path to the image file
    ImageMode $mode = ImageMode::NONE,
    Gravity $gravity = Gravity::CENTER,
)

• file: Source image file path passed to new Imagick($file).
• mode (ImageMode): Controls scaling/cropping behavior.
  • NONE: Use original image size; if larger than the box, crop to fit (no scaling).
  • FIT: Scale down/up to fit entirely within the box (letterbox may appear), then position by gravity.
  • FILL: Scale to fully cover the box, then crop overflow based on gravity.
• gravity (Gravity): Aligns the image inside the available box. Values include TOP_LEFT, TOP, TOP_RIGHT, LEFT, CENTER, RIGHT, BOTTOM_LEFT, BOTTOM, BOTTOM_RIGHT.

Example

$drawBorder = draw(stroke: 'black', strokeWidth: 10);

$image = new Image(
    'image.jpg',
    ImageMode::FILL,
    Gravity::CENTER,
);

// Optional spacing and border
$image->setMargin(10);
$image->setPadding(8);
$image->setBorder($drawBorder);

// Draw rectangle onto image
$image->draw($imagick, $x, $y, $width, $height);

Security

$file is passed straight to new Imagick($file) with no validation — unlike the template image node, this class does not check for ImageMagick coder/URI-scheme prefixes (https:, msl:, …), a leading | (ImageMagick’s pipe-delegate syntax, which executes the rest of the string as a shell command), or contain the path to a directory. If $file (or any part of it) comes from an untrusted source — user input, a form field, an uploaded config — validate/sanitize it yourself before constructing Image, e.g. by resolving it with realpath() and checking it stays inside an expected directory. Passing unsanitized untrusted input directly risks arbitrary local file reads (path traversal), arbitrary command execution (via the | pipe delegate), or SSRF/arbitrary-coder execution (the “ImageTragick” class of vulnerabilities, CVE-2016-3714).

If you’re building the tree from a template instead of constructing Image directly, use Template::withSettings(new TemplateSettings(imageBaseDir: ...)) to get this containment automatically — see Templates → Settings.

Template

The same image as a template:

{
    "type": "image",
    "file": "image.jpg",
    "mode": "fill",
    "gravity": "center",
    "margin": 10,
    "padding": 8,
    "border": { "stroke": "black", "strokeWidth": 10 }
}