PHPackages                             pupiq/image-scaler - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. pupiq/image-scaler

ActiveLibrary[Image & Media](/categories/media)

pupiq/image-scaler
==================

PHP library for image resizing, cropping and format conversion. Supports JPEG, PNG, animated GIF, WebP, AVIF and HEIC.

v0.7.4(2mo ago)08541MITPHPPHP >=7.4

Since Jan 12Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/yarri/ImageScaler)[ Packagist](https://packagist.org/packages/pupiq/image-scaler)[ Docs](https://github.com/yarri/ImageScaler)[ RSS](/packages/pupiq-image-scaler/feed)WikiDiscussions master Synced yesterday

READMEChangelogDependencies (8)Versions (15)Used By (1)

ImageScaler
===========

[](#imagescaler)

[![Build Status](https://camo.githubusercontent.com/0c1287df3705291ceba66d82d2a7198d79735d280c46df730e896f56a9d509a8/68747470733a2f2f6170702e7472617669732d63692e636f6d2f79617272692f496d6167655363616c65722e7376673f6272616e63683d6d6173746572)](https://app.travis-ci.com/yarri/ImageScaler)

Handy tool for image resizing. Produces well optimized images for web.

Supported input and output formats: **JPEG, PNG, GIF** (including animated), **WebP, AVIF, HEIC**.

Requirements
------------

[](#requirements)

- PHP >= 7.4
- ext-imagick >= 3.4
- pngquant (optional, required only for `PngquantOptimizer` filter)

Basic Usage
-----------

[](#basic-usage)

```
$scaler = new Pupiq\ImageScaler("/path/to/image.jpg");

// getting info about image
$scaler->getImageWidth(); // e.g. 1920
$scaler->getImageHeight(); // e.g. 1080
$scaler->getOrientation(); // 0, 1, 2 or 3 (i.e. 0, 90, 180, 270 degrees clockwise)
$scaler->getMimeType(); // "image/jpeg"

// performing a transformation
$scaler->scaleTo(300,200,["keep_aspect" => true]);

// saving to output file
$scaler->saveTo("/path/to/output_file.jpg");
// or saving to string
// $image = $scaler->saveToString();

// checking the result
$scaler_out = new Pupiq\ImageScaler("/path/to/output_file.jpg");
$scaler_out->getImageWidth(); // 300
$scaler_out->getImageHeight(); // 169

```

EXIF orientation is detected automatically for JPEG images. The image is rotated accordingly so that the output is always correctly oriented.

Scaling options
---------------

[](#scaling-options)

There are plenty of options in method scaleTo(). Some of them are mutually exclusive and should not be used together.

```
$scaler->scaleTo($width, $height, [
  "orientation" => 0, // automatically detected from EXIF; 0, 1, 2 or 3 (i.e. 0, 90, 180, 270 degrees clockwise)

  // source crop area within the original image
  "x" => 0,
  "y" => 0,
  "width" => $image_width,
  "height" => $image_height,

  // keep_aspect and crop are mutually exclusive
  "keep_aspect" => false,
  "crop" => null, // null, true/"auto", "top", "bottom"

  "strip_meta_data" => true,
  "sharpen_image" => null, // true, false, null (auto: sharpens when downscaling by more than 20%)
  "compression_quality" => 85,
  "auto_convert_cmyk_to_rgb" => true,

  "output_format" => "jpeg", // "jpeg", "png", "gif", "webp", "avif", "heic"

  "background_color" => "#ffffff", // defaults to "transparent" for png, gif, webp and avif
]);

```

Typical usages
--------------

[](#typical-usages)

```
// Scale image to 200px width, preserve aspect ratio.
$scaler->scaleTo(200);

// Scale image to 200px height, preserve aspect ratio.
$scaler->scaleTo(null, 200);

// Scale image to fit into a 200x200 box.
// Aspect ratio is preserved; any remaining space is filled with background_color.
$scaler->scaleTo(200, 200, ["background_color" => "#ffffff"]);

// Scale image to fit within 200x200.
// The output may be smaller than 200x200 in one dimension.
$scaler->scaleTo(200, 200, ["keep_aspect" => true]);

// Scale and crop the image to exactly 200x200.
// The crop is centred.
$scaler->scaleTo(200, 200, ["crop" => true]);

// Scale and crop to 200x200, preserving the top part of the image.
// Great for portrait photos, magazine covers, etc.
$scaler->scaleTo(200, 200, ["crop" => "top"]);

// Scale and crop to 200x200, preserving the bottom part of the image.
$scaler->scaleTo(200, 200, ["crop" => "bottom"]);

```

Format conversion
-----------------

[](#format-conversion)

The output format can be changed independently of the input format. To convert a JPEG to WebP:

```
$scaler = new Pupiq\ImageScaler("/path/to/image.jpg");
$scaler->scaleTo(800, null, ["output_format" => "webp"]);
$scaler->saveTo("/path/to/output_image.webp");

```

Any combination of supported input and output formats is accepted.

Filters
-------

[](#filters)

Image processing can be extended with filters. There are two types of filters.

- **After scale filters**
    Executed right after scaling. The `Imagick` object is passed to them.
    Must be an instance of `Pupiq\ImageScaler\AfterScaleFilter`.
- **After save filters**
    Executed right after the image is saved to the output file. The filename is passed to them.
    Must be an instance of `Pupiq\ImageScaler\AfterSaveFilter`.

In both types the scaling options array is also passed to the filter.

This package comes with several built-in filters.

#### Grayscale filter

[](#grayscale-filter)

Converts the processed image to grayscale. It is an after scale filter.

```
$scaler = new Pupiq\ImageScaler("/path/to/image.jpg");
$scaler->appendAfterScaleFilter(new Pupiq\ImageScaler\GrayscaleFilter());

$scaler->scaleTo(300, 300);
$scaler->saveTo("/path/to/output_image.jpg"); // grayscale

```

#### Pngquant Optimizer filter

[](#pngquant-optimizer-filter)

Significantly reduces the file size of PNG images using the [pngquant](https://pngquant.org/) binary. It is an after save filter and has no effect on non-PNG output formats.

```
$scaler = new Pupiq\ImageScaler("/path/to/image.png");
$scaler->appendAfterSaveFilter(new Pupiq\ImageScaler\PngquantOptimizer([
  "pngquant_binary" => "/usr/bin/pngquant", // default: "pngquant"
  "quality_range" => "70-90"                // default: "70-90"
]));

$scaler->scaleTo(300, 300);
$scaler->saveTo("/path/to/output_image.png");

```

#### Watermark filter

[](#watermark-filter)

Places a watermark image over the processed image. It is an after scale filter.

```
$scaler = new Pupiq\ImageScaler("/path/to/image.jpg");
$scaler->appendAfterScaleFilter(new Pupiq\ImageScaler\WatermarkFilter("/path/to/watermark_image.png", [
  "opacity" => 50,          // percentage, default: 50
  "position" => "center",   // "center", "left-top", "left-bottom", "right-top", "right-bottom"; default: "center"
]));

$scaler->scaleTo(300, 300);
$scaler->saveTo("/path/to/output_image.jpg"); // watermarked image

```

#### Combining filters

[](#combining-filters)

Filters can be combined and are applied in the order they were added.

```
$scaler = new Pupiq\ImageScaler("/path/to/image.jpg");

$scaler->appendAfterScaleFilter(new Pupiq\ImageScaler\WatermarkFilter("/path/to/watermark_image.png"));
$scaler->appendAfterScaleFilter(new Pupiq\ImageScaler\GrayscaleFilter());

$scaler->scaleTo(300, 300);
$scaler->saveTo("/path/to/output_image.jpg"); // watermarked and grayscaled

```

Installation
------------

[](#installation)

Use the Composer:

```
composer require pupiq/image-scaler

```

Testing
-------

[](#testing)

Install required dependencies:

```
composer update

```

Run tests:

```
cd test
../vendor/bin/run_unit_tests

```

License
-------

[](#license)

ImageScaler is free software distributed [under the terms of the MIT license](http://www.opensource.org/licenses/mit-license)

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance84

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~207 days

Recently: every ~261 days

Total

12

Last Release

80d ago

PHP version history (2 changes)v0.1PHP >=5.3.0

v0.7.4PHP >=7.4

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/974278?v=4)[Jaromir Tomek](/maintainers/yarri)[@yarri](https://github.com/yarri)

---

Top Contributors

[![yarri](https://avatars.githubusercontent.com/u/974278?v=4)](https://github.com/yarri "yarri (119 commits)")

---

Tags

imageresizewatermarkscale

### Embed Badge

![Health badge](/badges/pupiq-image-scaler/health.svg)

```
[![Health](https://phpackages.com/badges/pupiq-image-scaler/health.svg)](https://phpackages.com/packages/pupiq-image-scaler)
```

###  Alternatives

[intervention/image

PHP Image Processing

14.3k208.9M2.6k](/packages/intervention-image)[gumlet/php-image-resize

PHP class to re-size and scale images

1.2k6.0M66](/packages/gumlet-php-image-resize)[sybio/image-workshop

Powerful PHP class using GD library to work easily with images including layer notion (like Photoshop or GIMP)

854945.6k12](/packages/sybio-image-workshop)[intervention/image-laravel

Laravel Integration of Intervention Image

1588.9M186](/packages/intervention-image-laravel)[jbzoo/image

A PHP class that simplifies working with images

174129.4k3](/packages/jbzoo-image)[coldume/imagecraft

A reliable and extensible PHP image manipulation library

10034.1k2](/packages/coldume-imagecraft)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)