php-image-resize

PHP library to resize, scale and crop images.

Cloud Solution

If you don't want to crop, resize and store images on your server, Gumlet.com is a free service which can process images in real-time and serve worldwide through CDN.

---

Setup

This package is available through Packagist with the vendor and package identifier the same as this repo.

If using Composer, in your composer.json file add:

{
    "require": {
        "gumlet/php-image-resize": "^3.0"
    }
}

PHP 8.1 or newer is required (with the gd and fileinfo extensions). For older PHP versions, stay on the 2.x line:

Upgrading from 2.x to 3.0

3.0 is a major release focused on modern PHP, static analysis, and PHP 8.5 compatibility. Behavior is largely the same; most upgrades are about types and environment.

Requirements

• PHP >= 8.1 (2.x supported older PHP).
• ext-gd and ext-fileinfo (unchanged).

Breaking / API changes

• Typed public API — Methods and public properties use scalar types and static return types (e.g. resize(int $width, int $height, bool $allow_enlarge = false): static). Custom subclasses that override methods must match these signatures.
• ImageResize::__construct(string $filename) — The path must be a non-empty string. Passing null is a TypeError in PHP 8+ (previously you could pass null and get ImageResizeException). Use a real path, a data: URL, or ImageResize::createFromString() for binary data.
• ImageResize::createFromString(string $image_data) — Only accepts string; empty string still throws ImageResizeException with message image_data must not be empty.
• save() signature — Documented types: string|resource|null $filename, optional ?int $image_type, int|string|null $quality, ?int $permissions, and array|false $exact_size (canvas size [width, height], not a boolean).
• Class constants — Crop/flip constants are public const on ImageResize (same names and values as before).
• BMP output — imagebmp() is called without a invalid third argument (fixes deprecation when quality was null).

Fixes (compatible behavior)

• MIME detection via finfo runs only when getimagesize() fails (no finfo_open on every load).
• chmod after save only runs when the destination is a file path string (not streams or null used by output()).
• PHP 8.5: removed deprecated finfo_close() usage.

Development / quality (library consumers unaffected unless you contribute)

• PSR-12 via PHP-CS-Fixer (composer cs-fix / cs-check).
• PHPStan level 3 on lib/ (composer phpstan).
• PHPUnit 10+ config migrated; CI runs tests on PHP 8.2–8.5 and a separate static-analysis job.
• Expanded test suite (missing file, exact_size, enlarge, WebP/AVIF save, gamma, filters).

See CHANGELOG.md for the full 3.0.0 release notes.

Otherwise:

include '/path/to/ImageResize.php';

Because this class uses namespacing, when instantiating the object, you need to either use the fully qualified namespace:

$image = new \Gumlet\ImageResize();

Or alias it:

use \Gumlet\ImageResize;

$image = new ImageResize();

Note: This library uses GD class which do not support resizing animated gif files

---

Resize

To scale an image, in this case to half it's size (scaling is percentage based):

$image = new ImageResize('image.jpg');
$image->scale(50);
$image->save('image2.jpg');

To resize an image according to one dimension (keeping aspect ratio):

$image = new ImageResize('image.jpg');
$image->resizeToHeight(500);
$image->save('image2.jpg');

$image = new ImageResize('image.jpg');
$image->resizeToWidth(300);
$image->save('image2.jpg');

To resize an image according to a given measure regardingless its orientation (keeping aspect ratio):

$image = new ImageResize('image.jpg');
$image->resizeToLongSide(500);
$image->save('image2.jpg');

$image = new ImageResize('image.jpg');
$image->resizeToShortSide(300);
$image->save('image2.jpg');

To resize an image to best fit a given set of dimensions (keeping aspet ratio):

$image = new ImageResize('image.jpg');
$image->resizeToBestFit(500, 300);
$image->save('image2.jpg');

All resize functions have $allow_enlarge option which is set to false by default. You can enable by passing true to any resize function:

$image = new ImageResize('image.jpg');
$image->resize(500, 300, $allow_enlarge = True);
$image->save('image2.jpg');

If you are happy to handle aspect ratios yourself, you can resize directly:

$image = new ImageResize('image.jpg');
$image->resize(800, 600);
$image->save('image2.jpg');

This will cause your image to skew if you do not use the same width/height ratio as the source image.

Crop

To to crop an image:

$image = new ImageResize('image.jpg');
$image->crop(200, 200);
$image->save('image2.jpg');

This will scale the image to as close as it can to the passed dimensions, and then crop and center the rest.

In the case of the example above, an image of 400px × 600px will be resized down to 200px × 300px, and then 50px will be taken off the top and bottom, leaving you with 200px × 200px.

Crop modes:

Few crop mode options are available in order for you to choose how you want to handle the eventual exceeding width or height after resizing down your image. The default crop mode used is the CROPCENTER. As a result those pieces of code are equivalent:

$image = new ImageResize('image.jpg');
$image->crop(200, 200);
$image->save('image2.jpg');

$image = new ImageResize('image.jpg');
$image->crop(200, 200, true, ImageResize::CROPCENTER);
$image->save('image2.jpg');

In the case you have an image of 400px × 600px and you want to crop it to 200px × 200px the image will be resized down to 200px × 300px, then you can indicate how you want to handle those 100px exceeding passing the value of the crop mode you want to use.

For instance passing the crop mode CROPTOP will result as 100px taken off the bottom leaving you with 200px × 200px.

$image = new ImageResize('image.jpg');
$image->crop(200, 200, true, ImageResize::CROPTOP);
$image->save('image2.jpg');

On the contrary passing the crop mode CROPBOTTOM will result as 100px taken off the top leaving you with 200px × 200px.

$image = new ImageResize('image.jpg');
$image->crop(200, 200, true, ImageResize::CROPBOTTOM);
$image->save('image2.jpg');

Freecrop:

There is also a way to define custom crop position. You can define $x and $y in freecrop method:

$image = new ImageResize('image.jpg');
$image->freecrop(200, 200, $x =  20, $y = 20);
$image->save('image2.jpg');

Loading and saving images from string

To load an image from a string:

$image = ImageResize::createFromString(base64_decode('R0lGODlhAQABAIAAAAQCBP///yH5BAEAAAEALAAAAAABAAEAAAICRAEAOw=='));
$image->scale(50);
$image->save('image.jpg');

You can also return the result as a string:

$image = ImageResize::createFromString(base64_decode('R0lGODlhAQABAIAAAAQCBP///yH5BAEAAAEALAAAAAABAAEAAAICRAEAOw=='));
$image->scale(50);
echo $image->getImageAsString();

Magic __toString() is also supported:

$image = ImageResize::createFromString(base64_decode('R0lGODlhAQABAIAAAAQCBP///yH5BAEAAAEALAAAAAABAAEAAAICRAEAOw=='));
$image->resize(10, 10);
echo (string)$image;

Displaying

As seen above, you can call $image->save('image.jpg');

To render the image directly into the browser, you can call $image->output();

Image Types

When saving to disk or outputting into the browser, the script assumes the same output type as input.

If you would like to save/output in a different image type, you need to pass a (supported) PHP IMAGETYPE_* constant:

• IMAGETYPE_GIF
• IMAGETYPE_JPEG
• IMAGETYPE_PNG
• IMAGETYPE_WEBP (when GD is built with WebP support)
• IMAGETYPE_AVIF (when GD is built with AVIF support)
• IMAGETYPE_BMP

This allows you to save in a different type to the source:

$image = new ImageResize('image.jpg');
$image->resize(800, 600);
$image->save('image.png', IMAGETYPE_PNG);

Quality

The properties $quality_jpg, $quality_webp and $quality_png are available for you to configure:

$image = new ImageResize('image.jpg');
$image->quality_jpg = 100;
$image->resize(800, 600);
$image->save('image2.jpg');

By default they are set to 85, 85 (WebP), 60 (AVIF), and 6 (PNG) respectively. See the manual entries for imagejpeg() and imagepng() for more info.

You can also pass the quality directly to the save(), output() and getImageAsString() methods:

$image = new ImageResize('image.jpg');
$image->crop(200, 200);
$image->save('image2.jpg', null, 100);

$image = new ImageResize('image.jpg');
$image->resizeToWidth(300);
$image->output(IMAGETYPE_PNG, 4);

$image = new ImageResize('image.jpg');
$image->scale(50);
$result = $image->getImageAsString(IMAGETYPE_PNG, 4);

We're passing null for the image type in the example above to skip over it and provide the quality. In this case, the image type is assumed to be the same as the input.

Interlacing

By default, image interlacing is turned on. It can be disabled by setting $interlace to 0:

$image = new ImageResize('image.jpg');
$image->scale(50);
$image->interlace = 0;
$image->save('image2.jpg');

Chaining

When performing operations, the original image is retained, so that you can chain operations without excessive destruction.

This is useful for creating multiple sizes:

$image = new ImageResize('image.jpg');
$image
    ->scale(50)
    ->save('image2.jpg')

    ->resizeToWidth(300)
    ->save('image3.jpg')

    ->crop(100, 100)
    ->save('image4.jpg')
;

Input Limit

This library imposes input image pixel limit of 15,000,000 pixels (3873x3873) to prevent decompression bombs. If you want to raise this limit, you can do it like this.

$image->max_source_pixels = 30_000_000;

// or you can completely disable the limit for trusted input
$image->max_source_pixels = 0;

Exceptions

ImageResize throws ImageResizeException for it's own for errors. You can catch that or catch the general \Exception which it's extending.

It is not to be expected, but should anything go horribly wrong mid way then notice or warning Errors could be shown from the PHP GD and Image Functions (http://php.net/manual/en/ref.image.php)

try {
    new ImageResize('/path/that/does/not/exist.jpg');
} catch (ImageResizeException $e) {
    echo 'Something went wrong: ' . $e->getMessage();
}

Filters

You can apply special effects for new image like blur or add banner.

$image = new ImageResize('image.jpg');

// Add blure
$image->addFilter(function ($imageDesc) {
    imagefilter($imageDesc, IMG_FILTER_GAUSSIAN_BLUR);
});

// Add banner on bottom left corner
$image18Plus = 'banner.png'
$image->addFilter(function ($imageDesc) use ($image18Plus) {
    $logo = imagecreatefrompng($image18Plus);
    $logo_width = imagesx($logo);
    $logo_height = imagesy($logo);
    $image_width = imagesx($imageDesc);
    $image_height = imagesy($imageDesc);
    $image_x = $image_width - $logo_width - 10;
    $image_y = $image_height - $logo_height - 10;
    imagecopy($imageDesc, $logo, $image_x, $image_y, 0, 0, $logo_width, $logo_height);
});

Flip

Flips an image using a given mode and this method is only for PHP version 5.4.

$flip = new ImageResize('image.png');
$image = imagecreatetruecolor(200, 100);

$image->addFilter(function ($image) {
    imageflip($image, IMG_FLIP_HORIZONTAL);
});

Both functions will be used in the order in which they were added.

Gamma color correction

You can enable the gamma color correction which is disabled by default.

$image = new ImageResize('image.png');
$image->gamma(true);

API Doc

https://gumlet.github.io/php-image-resize/index.html

---

Maintainer

This library is maintained by Gumlet.com