README

A PHP library for creating complex image layouts with automatic positioning and sizing. This library provides a flexbox-like approach to image composition, making it easy to create structured layouts with text, images, and shapes.

Requirements

PHP 8.3 or later
Linux (Windows not tested)
Imagick PHP extension

Installation

You can install the package via composer:

composer require kehet/imagick-layout-engine

Basic Usage

// Create a new image
$width = 1500;
$height = 1000;
$imagick = new Imagick();
$imagick->newImage($width, $height, new ImagickPixel('white'));

// Create a row container with rectangles
$frame = new RowContainer();
$frame->addItem(new Rectangle(draw(fill: '#fee2e2')));
$frame->addItem(new Rectangle(draw(fill: '#fca5a5')));
$frame->addItem(new Rectangle(draw(fill: '#dc2626')));
$frame->addItem(new Rectangle(draw(fill: '#450a0a')));

// Draw container onto image
$frame->draw($imagick, 0, 0, $width, $height);

// Output image as PNG
$imagick->setImageFormat('png');
$imagick->writeImage('output.png');

For more examples, see documentation.

Testing

composer test

SAVE_SNAPSHOT

When set, if snapshot file is missing, snapshot image will be automatically written to tests/__snapshots__/.

SAVE_SNAPSHOT=1 composer test -- --filter=YourTest

SAVE_IMAGE_DIFF

When set, a visual diff image will be saved to tests/temp/ whenever an image comparison is performed, regardless of pass/fail.

SAVE_IMAGE_DIFF=1 composer test -- --filter=YourTest

Running tests in Docker

If you'd rather not use your host PHP install, a Dockerfile is provided to run the test suite in a container instead. It doesn't copy the source or install dependencies at build time — the project directory is bind-mounted at run time, so code changes are picked up without rebuilding. Build with USER_ID/GROUP_ID set to your host user so bind-mounted output (tests/temp/, vendor/) is written back with your own permissions instead of the container's:

docker build --build-arg USER_ID="$(id -u)" --build-arg GROUP_ID="$(id -g)" -t imagick-layout-engine-test .

Install dependencies once (and again whenever composer.json/composer.lock change) by running Composer inside the container — it writes vendor/ straight to the host through the bind mount:

docker run --rm -v "$(pwd):/var/www/html" imagick-layout-engine-test composer install --no-interaction --no-progress --prefer-dist

Run the suite:

docker run --rm -v "$(pwd):/var/www/html" imagick-layout-engine-test

To inspect snapshot diffs on the host, set SAVE_IMAGE_DIFF (they land in tests/temp/ since the project is already mounted):

docker run --rm -e SAVE_IMAGE_DIFF=1 -v "$(pwd):/var/www/html" imagick-layout-engine-test

To write a missing snapshot, set SAVE_SNAPSHOT:

docker run --rm -e SAVE_SNAPSHOT=1 -v "$(pwd):/var/www/html" \
  imagick-layout-engine-test composer test -- --filter=YourTest

Roadmap

Please see ROADMAP for more information on the future of this project.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

License

GNU GENERAL PUBLIC LICENSE version 3 or later. Please see License File for more information.

kehet / imagick-layout-engine

Maintainers

Package info

Fund package maintenance!

Statistics

Security