byjg / imageutil

6.0.0 2025-11-25 00:14 UTC

Requires

• php: >=8.3 <8.6
• ext-gd: *
• meyfa/php-svg: ^v0

Requires (Dev)

• ext-imagick: *
• phpunit/phpunit: ^10.5|^11.5
• vimeo/psalm: ^5.9|^6.13

MIT

Published on Packagist.org on 2025-11-26 03:14 UTC

README

sidebar_key	imageutil
tags	php image

Image Manipulation Library

ImageUtil is a PHP library that provides a collection of operations for image manipulation using the GD library. It simplifies tasks such as flipping, cropping, resizing, stamping, and more.

Installation

To install ImageUtil, use the following composer command:

composer require "byjg/imageutil"

Supported Formats

ImageUtil supports the following image formats:

• GIF
• JPEG
• PNG
• BMP
• WEBP
• SVG (Partial support. Primarily for converting SVG to other formats, not for SVG manipulation.)

Creating an Image

You can create an image from a file, URL, existing resource, or create an empty image:

<?php
use ByJG\ImageUtil\ImageUtil;
use ByJG\ImageUtil\Color;
use ByJG\ImageUtil\Enum\FileType;

// From a file
$img = ImageUtil::fromFile('path_to_image.png');

// From a URL. The format comes from the extension in the path, so a query string is fine
$img2 = ImageUtil::fromFile('https://somesite/someimage.jpg?size=large');

// From an existing resource image
$resourceImg = imagecreatetruecolor(200, 300);
$img3 = ImageUtil::fromResource($resourceImg);

// Or an empty image
$img4 = ImageUtil::empty(200, 300, FileType::Png, new Color(255, 255, 255));

SVG Files

:::caution ImageUtil provides basic support for SVG files, primarily for converting SVG images to other GD-supported formats. It does not support all SVG features and does not support operations like resize, flip, etc. :::

<?php
use ByJG\ImageUtil\ImageUtil;

$img = ImageUtil::fromFile('path_to_image.svg');
$img->save('path_to_image.png');

Image Manipulation

ImageUtil provides several methods for image manipulation:

• Flip: Mirror the image vertically or horizontally.
• Rotate: Rotate the image by a specified angle.
• Resize: Resize the image to specified dimensions.
• Resize Square: Resize the image to a square format while maintaining the aspect ratio. Any extra space is filled with the provided RGB color.
• Resize AspectRatio: Resize the image while maintaining the aspect ratio. Any extra space is filled with the provided RGB color.
• Stamp Image: Stamp another image onto the current image.
• Write Text: Write text onto the image.
• Crop Image: Crop the image from a specified point to another point.
• Make Transparent: Make the image transparent. The transparent color must be provided.

See detailed examples here.

Saving and Restoring Changes

You can discard the changes and go back to the image as it was loaded, or save them:

<?php
use ByJG\ImageUtil\ImageUtil;

$img = ImageUtil::fromFile('wheel.png');
$img->resize(640, 480);

// Discard the resize: the image is back to what was loaded
$img->restore();

$img->resize(320, 240);

// Save to file. The format comes from the extension
$img->save('filename.gif');

:::note save() makes the saved image the new starting point: a restore() after it goes back to what was saved, not to what was first loaded. :::

Other Functions

ImageUtil also provides methods to get the image dimensions and the image resource:

<?php
use ByJG\ImageUtil\ImageUtil;

$img = ImageUtil::fromFile('wheel.png');

$width = $img->getWidth();
$height = $img->getHeight();
$resource = $img->getResource();   // the GdImage
$filename = $img->getFilename();   // the file it was loaded from or last saved to

Colors, text alignment, stamp options, sending the image to the browser and adding a custom format are covered in the examples.

Dependencies

ImageUtil depends on the GD extension for PHP (ext-gd, required in composer.json).

Running Tests

vendor/bin/phpunit

Open source ByJG