PHPackages                             wjerome/imagine - 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. wjerome/imagine

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

wjerome/imagine
===============

Imagine (image-engine) is a PHP micro library to resize, thumbnail or apply filters to your images

2.5.0(3y ago)222[5 issues](https://github.com/w-jerome/imagine/issues)MITPHPPHP >=7.2

Since Jan 23Pushed 3y ago1 watchersCompare

[ Source](https://github.com/w-jerome/imagine)[ Packagist](https://packagist.org/packages/wjerome/imagine)[ RSS](/packages/wjerome-imagine/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (8)Dependencies (3)Versions (10)Used By (0)

Imagine
=======

[](#imagine)

🖼 Imagine (image-engine) is a PHP micro library to resize, thumbnail or apply filters to your images

Required
--------

[](#required)

- PHP >= 7.2
- GD

File types supported
--------------------

[](#file-types-supported)

- jpg
- png
- gif
- webp
- bmp

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

[](#installation)

```
composer require wjerome/imagine
```

Usage
-----

[](#usage)

```
use Imagine\Imagine;

try {
  $image = new Imagine($_FILES['image']['tmp_name']);
  $image->setWidth(200);
  $image->setHeight(290);
  $image->save('./uploads/my-image.jpg');
} catch (Exception $e) {
  echo 'Exception: ' . $e->getMessage();
}
```

```
// Chaining methods
(new Imagine('./my-image.jpg'))
  ->setWidth(200)
  ->setHeight(200)
  ->setQuality(90)
  ->setFit('cover')
  ->save('./uploads/my-image.jpg');
```

### Functions

[](#functions)

```
// File upload
$image = new Imagine($_FILES['image']['tmp_name']);

// Or a file in a folder
$image = new Imagine('./my-picture.jpg');

// Setter
$image->setWidth(200);
$image->setHeight(290);
$image->setType('png');
$image->setDPI(96);
$image->setQuality(90);
$image->setCropAuto();
$image->setCropFromPixel(0, 0, 300, 300);
$image->setCropFromPercent(0, 0, 100, 100);
$image->setFit('cover');
$image->setPosition('left', 'top');
$image->setBackgroundFromRGBA(255, 255, 255, 1);
$image->setBackgroundFromHexa('#ffaaff');
$image->setBackgroundTransparent();
$image->setBackgroundMainColor();
$image->addFilter(IMG_FILTER_GRAYSCALE);
$image->setIsInterlace(true);
$image->setIsOverride(false);
$image->reset();

// Getter
$image->getSrcWidth();
$image->getSrcHeight();
$image->getSrcMime();
$image->getSrcType();
$image->getSrcDPI();
$image->getDistWidth();
$image->getDistHeight();
$image->getDistMime();
$image->getDistType();
$image->getDistDPI();
$image->getQuality();
$image->getCropAuto();
$image->getCropType();
$image->getCropSize();
$image->getFit();
$image->getPosition();
$image->getBackground();
$image->getBackgroundFromHexa();
$image->getFilters();
$image->getIsInterlace();
$image->getIsOverride();

// Save file
$image->save('./uploads/my-image.jpg');
$image->saveAndContinue('./uploads/my-image.jpg');
$image->saveAndReset('./uploads/my-image.jpg');

// Or render in browser
$image->displayOnBrowser();
```

Examples
--------

[](#examples)

### Resize width

[](#resize-width)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->save('./doc/img/example-01.jpg');
```

[![example 01](/doc/img/example-01.jpg)](/doc/img/example-01.jpg)

### Resize height

[](#resize-height)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setHeight(300);
$image->save('./doc/img/example-02.jpg');
```

[![example 02](/doc/img/example-02.jpg)](/doc/img/example-02.jpg)

### Create thumbnail fit "stretch"

[](#create-thumbnail-fit-stretch)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->setHeight(300);
$image->save('./doc/img/example-03.jpg');
```

[![example 03](/doc/img/example-03.jpg)](/doc/img/example-03.jpg)

### Create thumbnail fit "contain"

[](#create-thumbnail-fit-contain)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->setHeight(300);
$image->setFit('contain');
$image->save('./doc/img/example-04.jpg');
```

[![example 04](/doc/img/example-04.jpg)](/doc/img/example-04.jpg)

### Create thumbnail fit "cover"

[](#create-thumbnail-fit-cover)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->setHeight(300);
$image->setFit('cover');
$image->save('./doc/img/example-05.jpg');
```

[![example 05](/doc/img/example-05.jpg)](/doc/img/example-05.jpg)

### Background color transparent

[](#background-color-transparent)

```
$image = new Imagine('./tests/assets/file-transparent.png');
$image->setWidth(300);
$image->setHeight(300);
$image->setBackgroundTransparent();
$image->save('./doc/img/example-06.png');
```

[![example 06](/doc/img/example-06.png)](/doc/img/example-06.png)

### Background color main color

[](#background-color-main-color)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->setHeight(300);
$image->setBackgroundMainColor();
$image->save('./doc/img/example-07.jpg');
```

[![example 07](/doc/img/example-07.jpg)](/doc/img/example-07.jpg)

### Background color with array

[](#background-color-with-array)

```
$image = new Imagine('./tests/assets/file-transparent.png');
$image->setWidth(300);
$image->setHeight(300);
$image->setBackgroundFromRGBA(255, 0, 0, 1);
$image->setType('jpg');
$image->save('./doc/img/example-08.jpg');
```

[![example 08](/doc/img/example-08.jpg)](/doc/img/example-08.jpg)

### Background color with hexa

[](#background-color-with-hexa)

```
$image = new Imagine('./tests/assets/file-transparent.png');
$image->setWidth(300);
$image->setHeight(300);
$image->setBackgroundFromHexa('#ffaaff');
$image->setType('jpg');
$image->save('./doc/img/example-09.jpg');
```

[![example 09](/doc/img/example-09.jpg)](/doc/img/example-09.jpg)

### Image position in thumbnail

[](#image-position-in-thumbnail)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->setHeight(300);
$image->setPosition('left', 'top');
$image->save('./doc/img/example-10.jpg');
```

[![example 10](/doc/img/example-10.jpg)](/doc/img/example-10.jpg)

### Quality

[](#quality)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->setQuality(50); // percent
$image->save('./doc/img/example-11.jpg');
```

[![example 11](/doc/img/example-11.jpg)](/doc/img/example-11.jpg)

#### Note: 1

[](#note-1)

In PNG the quality is not a percentage, it is a value between `0` and `9`. `0` corresponds to no compression and `9` corresponds to the maximum compression. Here are the values to fill in `$image->setQuality()` :

- `setQuality(0)` : compression `9`
- `setQuality(1) -> setQuality(11)` : compression `8`
- `setQuality(12) -> setQuality(22)` : compression `7`
- `setQuality(23) -> setQuality(33)` : compression `6`
- `setQuality(34) -> setQuality(44)` : compression `5`
- `setQuality(45) -> setQuality(55)` : compression `4`
- `setQuality(56) -> setQuality(66)` : compression `3`
- `setQuality(67) -> setQuality(77)` : compression `2`
- `setQuality(78) -> setQuality(88)` : compression `1`
- `setQuality(89) -> setQuality(100)` : compression `0` (Be careful, the file size can be important)

[For more information](https://www.php.net/manual/en/function.imagepng.php)

#### Note: 2

[](#note-2)

By default the quality is 100%, but if we process a PNG file, it will go through the `imagepng()` function and the 100% quality makes the destination image much heavier than the source image (up to 11 times the original file size). So to avoid abuse, by default PNGs have a quality of 0% (which corresponds to a compression of `9`).

### Crop auto

[](#crop-auto)

Crop the destination image by calculating the unused pixels

```
$image = new Imagine('./tests/assets/file-transparent-border.png');
$image->setBackgroundFromHexa('#ccc');
$image->setWidth(300);
$image->setCropAuto();
$image->save('./doc/img/example-16.jpg');
```

[![example 16](/doc/img/example-16.jpg)](/doc/img/example-16.jpg)

### Manual cropping (in pixel)

[](#manual-cropping-in-pixel)

Crop the destination image by passing the position and size in pixels

```
$image = new Imagine('./tests/assets/file-transparent-border.png');
$image->setBackgroundFromHexa('#ccc');
$image->setCropFromPixel(300, 150, 300, 150);
$image->save('./doc/img/example-17.jpg');
```

[![example 17](/doc/img/example-17.jpg)](/doc/img/example-17.jpg)

### Manual cropping (in percent)

[](#manual-cropping-in-percent)

Crop the destination image by passing the position and size in percent

```
$image = new Imagine('./tests/assets/file-transparent-border.png');
$image->setBackgroundFromHexa('#ccc');
$image->setWidth(300);
$image->setCropFromPercent(25, 25, 50, 50);
$image->save('./doc/img/example-18.jpg');
```

[![example 18](/doc/img/example-18.jpg)](/doc/img/example-18.jpg)

### Convert MIME file

[](#convert-mime-file)

```
$image = new Imagine('./tests/assets/file-transparent.png');
$image->setWidth(300);
$image->setType('jpg'); // jpg|jpeg|png|gif|webp|bmp
$image->save('./doc/img/example-12.jpg');
```

[![example 12](/doc/img/example-12.jpg)](/doc/img/example-12.jpg)

### Add grayscale filter

[](#add-grayscale-filter)

[The list of available filters](https://www.php.net/manual/function.imagefilter.php)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->addFilter(IMG_FILTER_GRAYSCALE);
$image->save('./doc/img/example-13.jpg');
```

[![example 13](/doc/img/example-13.jpg)](/doc/img/example-13.jpg)

### Add grayscale and blur filter

[](#add-grayscale-and-blur-filter)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->addFilter(IMG_FILTER_GRAYSCALE);
$image->addFilter(IMG_FILTER_GAUSSIAN_BLUR);
$image->addFilter(IMG_FILTER_GAUSSIAN_BLUR); // More blur
$image->addFilter(IMG_FILTER_GAUSSIAN_BLUR); // More more blur
$image->save('./doc/img/example-14.jpg');
```

[![example 14](/doc/img/example-14.jpg)](/doc/img/example-14.jpg)

### Display progressively the `jpg` and `jpeg` images

[](#display-progressively-the-jpg-and-jpeg-images)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->setWidth(300);
$image->setIsInterlace(true);
$image->save('./doc/img/example-15.jpg');
```

[![example 15](/doc/img/example-15.jpg)](/doc/img/example-15.jpg)

### Display on browser

[](#display-on-browser)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->displayOnBrowser();
```

### Create multiple images with a single resource

[](#create-multiple-images-with-a-single-resource)

#### Reset settings each time a file is written

[](#reset-settings-each-time-a-file-is-written)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->addFilter(IMG_FILTER_GRAYSCALE);
$image->setWidth(300);
$image->setHeight(300);
$image->setQuality(80);
$image->saveAndReset('./doc/img/example-16-1.jpg');
$image->setWidth(500);
$image->setFit('cover');
$image->saveAndReset('./doc/img/example-16-2.jpg');
$image->setWidth(1000);
$image->setQuality(100);
$image->save('./doc/img/example-16-3.jpg');
```

[![example 16-1](/doc/img/example-16-1.jpg)](/doc/img/example-16-1.jpg)[![example 16-2](/doc/img/example-16-2.jpg)](/doc/img/example-16-2.jpg)[![example 16-3](/doc/img/example-16-3.jpg)](/doc/img/example-16-3.jpg)

#### Keeps the previous configuration each time the file is written

[](#keeps-the-previous-configuration-each-time-the-file-is-written)

```
$image = new Imagine('./tests/assets/file-valid.jpg');
$image->addFilter(IMG_FILTER_GRAYSCALE);
$image->setWidth(300);
$image->setHeight(300);
$image->setQuality(80);
$image->saveAndContinue('./doc/img/example-16-4.jpg');
$image->setWidth(500);
$image->setFit('cover');
$image->saveAndContinue('./doc/img/example-16-5.jpg');
$image->setWidth(1000);
$image->setQuality(100);
$image->save('./doc/img/example-16-6.jpg');
```

[![example 16-4](/doc/img/example-16-4.jpg)](/doc/img/example-16-4.jpg)[![example 16-5](/doc/img/example-16-5.jpg)](/doc/img/example-16-5.jpg)[![example 16-6](/doc/img/example-16-6.jpg)](/doc/img/example-16-6.jpg)

###  Health Score

22

—

LowBetter than 22% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity9

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 98.9% 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 ~175 days

Recently: every ~35 days

Total

8

Last Release

1437d ago

Major Versions

1.0 → 2.0.02022-01-08

PHP version history (2 changes)1.0PHP >=5.4.0

2.0.0PHP >=7.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/f92310287db168bd8da8a7b15d26e9e0849a6c7ab9a30d7fc32497d7e5f4bab8?d=identicon)[w-jerome](/maintainers/w-jerome)

---

Top Contributors

[![w-jerome](https://avatars.githubusercontent.com/u/1685550?v=4)](https://github.com/w-jerome "w-jerome (91 commits)")[![thomas-kl1](https://avatars.githubusercontent.com/u/20971693?v=4)](https://github.com/thomas-kl1 "thomas-kl1 (1 commits)")

---

Tags

phpthumbnailmicroimagegdresizelightcropfiltersengine

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/wjerome-imagine/health.svg)

```
[![Health](https://phpackages.com/badges/wjerome-imagine/health.svg)](https://phpackages.com/packages/wjerome-imagine)
```

###  Alternatives

[intervention/image

PHP Image Processing

14.3k194.3M2.2k](/packages/intervention-image)[stefangabos/zebra_image

A single-file, lightweight PHP library designed for efficient image manipulation featuring methods for modifying images and applying filters

141110.4k6](/packages/stefangabos-zebra-image)[sybio/image-workshop

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

860918.1k11](/packages/sybio-image-workshop)[jbzoo/image

A PHP class that simplifies working with images

171126.9k3](/packages/jbzoo-image)[intervention/image-laravel

Laravel Integration of Intervention Image

1496.5M100](/packages/intervention-image-laravel)[coldume/imagecraft

A reliable and extensible PHP image manipulation library

10133.7k2](/packages/coldume-imagecraft)

PHPackages © 2026

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