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 higher
Linux (Windows not tested)
Imagick PHP extension

Installation

You can install the package via composer:

composer require kehet/imagick-layout-engine

Basic Usage

// Helper function to create ImagickDraw objects with fill color
function fill(string $fill): ImagickDraw
{
    $return = new \ImagickDraw();
    $return->setFillColor(new \ImagickPixel($fill));
    return $return;
}

// 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(fill('#fee2e2')));
$frame->addItem(new Rectangle(fill('#fca5a5')));
$frame->addItem(new Rectangle(fill('#dc2626')));
$frame->addItem(new Rectangle(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 examples/

Features

Containers

The library provides two types of containers for layout:

RowContainer: Arranges items horizontally
ColumnContainer: Arranges items vertically

Containers can be nested to create complex layouts. When adding items to containers, you can specify an optional weight parameter to control the item's size relative to other items.

$row = new RowContainer();
$row->addItem(new Rectangle(fill('#fee2e2')), 50);  // 50 px wide
$row->addItem(new Rectangle(fill('#fca5a5')), 100); // 100 px wide
$row->addItem(new Rectangle(fill('#dc2626')));      // Takes remaining space

Padding

Containers support padding, which adds space between the container's edge and its content. The padding feature works similar to CSS padding, with support for one to four values:

Single value: applies the same padding to all sides
Two values: first value applies to top and bottom, second value applies to left and right
Three values: first value applies to top, second value applies to left and right, third value applies to bottom
Four values: values apply to top, right, bottom, and left, respectively

// Single value padding (10px on all sides)
$row = new RowContainer();
$row->addItem(new Rectangle(fill('#fee2e2')), padding: 10);
$row->addItem(new Rectangle(fill('#fca5a5')), padding: 10);

// Two value padding (10px top/bottom, 20px left/right)
$column = new ColumnContainer();
$column->addItem(new Rectangle(fill('#fee2e2')), padding: [10, 20]);
$column->addItem(new Rectangle(fill('#fca5a5')), padding: [10, 20]);

// Three value padding (10px top, 20px left/right, 30px bottom)
$row = new RowContainer();
$row->addItem(new Rectangle(fill('#fee2e2')), padding: [10, 20, 30]);
$row->addItem(new Rectangle(fill('#fca5a5')), padding: [10, 20, 30]);

// Four value padding (10px top, 20px right, 30px bottom, 40px left)
$column = new ColumnContainer();
$column->addItem(new Rectangle(fill('#fee2e2')), padding: [10, 20, 30, 40]);
$column->addItem(new Rectangle(fill('#fca5a5')), padding: [10, 20, 30, 40]);

Text Handling

The library provides two classes for text handling:

Text: Renders text with automatic font size adjustment to fit within the container
TextWrap: Renders text with automatic wrapping and font size adjustment

// Text with auto-sizing
$container->addItem(
    new Text(
        fill('#000'),
        'Lorem Ipsum Dolor',
        initialFontSize: 120,
        minFontSize: 50,
        gravity: Gravity::CENTER
    )
);

// Text with auto-wrapping and sizing
$container->addItem(
    new TextWrap(
        fill('#000'),
        'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
        initialFontSize: 60,
        minFontSize: 10
    )
);

Available gravity options:

Gravity::TOP_LEFT (default)
Gravity::TOP
Gravity::TOP_RIGHT
Gravity::LEFT
Gravity::CENTER
Gravity::RIGHT
Gravity::BOTTOM_LEFT
Gravity::BOTTOM
Gravity::BOTTOM_RIGHT

Image Handling

The library provides an Image class for adding images to layouts with various fitting and positioning options:

// Default behavior (fit) - maintains aspect ratio
$container->addItem(new Image('path/to/image.jpg'));

// Fill mode - image will be cropped to fill the container
$container->addItem(new Image('path/to/image.jpg', fill: ImageMode::FILL));

// With gravity option for positioning
$container->addItem(new Image('path/to/image.jpg', fill: ImageMode::FIT, gravity: Gravity::TOP));

Available gravity options:

Gravity::TOP_LEFT
Gravity::TOP
Gravity::TOP_RIGHT
Gravity::LEFT
Gravity::CENTER (default)
Gravity::RIGHT
Gravity::BOTTOM_LEFT
Gravity::BOTTOM
Gravity::BOTTOM_RIGHT

Advanced Examples

Nested Containers

// Create a column container with multiple row containers
$frame = new ColumnContainer();

// First row
$row = new RowContainer();
$row->addItem(new Rectangle(fill('#fee2e2')), 50);
$row->addItem(new Rectangle(fill('#fca5a5')), 100);
$row->addItem(new Rectangle(fill('#dc2626')), 150);
$row->addItem(new Rectangle(fill('#450a0a')));
$frame->addItem($row);

// Second row
$row = new RowContainer();
$row->addItem(new Rectangle(fill('#ecfccb')));
$row->addItem(new Rectangle(fill('#bef264')), 50);
$row->addItem(new Rectangle(fill('#65a30d')), 100);
$row->addItem(new Rectangle(fill('#1a2e05')), 150);
$frame->addItem($row);

Text and Images Together

// Create a column container with an image and text
$container = new ColumnContainer();
$container->addItem(new Image('path/to/image.jpg', fill: ImageMode::FIT, gravity: Gravity::CENTER));
$container->addItem(new TextWrap(fill('black'), 'Image Caption'));

Testing

composer test

Changelog

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

Roadmap

Margin / padding
Text background
Extract helper functions

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

kehet / imagick-layout-engine

Maintainers

Details