Imagine puts GD2, Imagick and Gmagick behind one PHP API, and leaves the first example to the docs

The extension you install decides what runs underneath

Imagine does not implement its own codecs. Its stated purpose is to bring all native low level image processing libraries in PHP behind the same simple and intuitive OO API, which means the extension on the host sets the ceiling. Three candidates are named: GD2, Imagick, and Gmagick, and the requirement is conditional, you may need one of them depending on the chosen implementation. That single decision shapes everything downstream. Moving from GD2 to Imagick is usually a change in what the deployment has rather than a rewrite of the calling code, and it is also how a feature quietly disappears from production: an operation one driver accepts and another rejects turns into a runtime failure on the box you deploy to. The project names Python's PIL as its inspiration.

PHP 7.1 is the floor, and older runtimes need older lines

The version mapping is the first thing to check on an inherited codebase:

| PHP runtime | Imagine version | | --- | --- | | 7.1 and newer | current release line | | 5.5 through 7.0 | ^1.3 | | 5.3 through 5.4 | ^1.2 |

Getting this wrong shows up as a composer conflict rather than an image error, and the remedy is a different branch of the library, not a change to your code. The Imagick driver carries a second constraint below the language version: ImageMagick 6.2.9 or later, with version 7.0.7-32 named as the exception. That exclusion is easy to miss on a host running an unusual ImageMagick build.

Autorotation goes quiet without the exif extension

Reading EXIF metadata is optional in Imagine, and the cost of leaving it out is easy to underestimate. The exif extension is what lets the library read and act on image orientation, and autorotation is the named example. Without the extension loaded the library still works: images open, resize and save. What you lose is the correction pass, so a photo taken in portrait reaches your pipeline with its orientation unread and every downstream consumer, thumbnailer or upload path, inherits the sideways original. The check belongs in your deployment: confirm the extension is present in the same PHP binary that runs the image job, since a CLI build and the web SAPI build can carry different extension sets.

The composer require line is the whole install procedure

Installation is one command, and there is no configuration file to fill in afterwards:

php composer.phar require imagine/imagine

Worth saying plainly: the README carries no PHP usage snippet at all, so the first real use means reading the hosted documentation rather than copying an example from the readme. What the README does describe is the three part surface the project calls its basic principles. Image manipulation tools such as resize and crop, a drawing API for basic shapes, advanced charts and text on the image, and masking, where a black and white or grayscale image is applied as a mask to produce semi transparency or absolute transparency. Those tools are the foundation for filters, and a separate list of filter ideas is marked as upcoming: charting and graphing with pie and bar charts and annotated linear graphs, apple style reflection, and rounded corners. Plan around the foundation, not that list.

The test container hides a setup the project calls very hard

Setting up an environment with all the required libraries may be very hard, and the project's answer is to stop doing it by hand. The images published under php-imagine/docker-builder are the same ones used to test pull requests:

docker run --rm -it -v /home/me/imagine:/app -w /app ghcr.io/php-imagine/test:8.1-gd-imagick bash

Inside the container the suite needs a local web server, because some tests require one:

cd tests
php -n -S 0.0.0.0:8013 >/dev/null 2>&1 &
cd ..
export IMAGINE_TEST_WEBSERVERURL=http://localhost:8013
composer update
composer run test -- --exclude-group always-skipped,gmagick

The `php -n` flag skips the ini file and the URL export tells the tests where to find that server, so the two belong together. Windows hosts mount a drive path in place of `/home/me/imagine`. The image tag carries the matrix, and 8.1-gd-imagick means PHP 8.1 with the GD and Imagick drivers, so testing any other combination means choosing a different tag.

Skipped tests are why a green run proves less than usual

Some PHPUnit tests are marked as skipped on purpose. Tests that need a driver supporting multiple layers are skipped when the suite runs on GD, and if gmagick is not installed the gmagick tests skip themselves. A green run on GD is therefore not a smaller version of the CI run, it is a different set of assertions, and the difference is easy to miss when the output is scrolled. The switch for taking the skips out of the way is a group exclusion:

composer run test -- --exclude-group always-skipped,gmagick

The same mechanism handles driver specific groups, named `gd` and `imagick` in the docs. What matters for a consumer is that your CI should pin the drivers your production hosts actually have, because a suite passing partly through skips will not warn you about a driver specific regression before a user does.

tests/tmp files vanish unless IMAGINE_TEST_KEEP_TEMPFILES is set

Many tests build an image into the `tests/tmp` directory, compare it with an expected image, and then delete it, so a failing comparison leaves you with a diff message and nothing to open. Setting the IMAGINE_TEST_KEEP_TEMPFILES environment variable keeps those files, and when it is configured in the action tests the temporary files are attached to the run as an artifact. That variable is the fastest route to seeing what an assertion actually produced. Branch policy is the other thing worth knowing before you open a pull request: new work should be based on `develop`, while `master` is the stable branch and usually matches the latest release but can be a bit ahead of it. A composer constraint that tracks a branch rather than a tag can therefore pick up unreleased work.

The tree itself is small and says where everything lives: `src/`, `tests/`, `docs/`, `CHANGELOG.md`, `MAINTAINERS.md`, `composer.json`, `phpunit.xml.dist` and `.php-cs-fixer.dist.php` at the root, plus a `LICENSE` file whose terms the README does not spell out, so read it before shipping this in a closed source product. Tags are recent: v1.5.4 and v1.5.3 landed a day apart in June 2026, v1.5.2 in January 2026, and the last push on record is 2026-06-04.

Editorial conclusion

Imagine fits teams whose deployment already has a chosen native extension and who want the same calling code across dev, CI and production. It is the wrong pick if you need a README level quick start, autorotation without the exif extension, or rounded corner and chart filters today. Verify which drivers the production host actually has, and confirm the ImageMagick build is not 7.0.7-32, before you pin a version.

Frequently asked questions

Official sources

1. Issues
2. php-imagine/Imagine on GitHub
3. Project website
4. README
5. Releases