PHPackages                             zenstruck/image - 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. zenstruck/image

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

zenstruck/image
===============

Image file wrapper with generic transformation support.

v1.1.0(5mo ago)3129.2k—3.6%11MITPHPPHP >=8.0CI passing

Since Jan 21Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/zenstruck/image)[ Packagist](https://packagist.org/packages/zenstruck/image)[ Docs](https://github.com/zenstruck/image)[ GitHub Sponsors](https://github.com/kbond)[ GitHub Sponsors](https://github.com/nikophil)[ RSS](/packages/zenstruck-image/feed)WikiDiscussions 1.x Synced 1mo ago

READMEChangelog (8)Dependencies (11)Versions (9)Used By (1)

zenstruck/image
===============

[](#zenstruckimage)

[![CI Status](https://github.com/zenstruck/image/workflows/CI/badge.svg)](https://github.com/zenstruck/image/actions?query=workflow%3ACI)[![codecov](https://camo.githubusercontent.com/166596df2883df5e62e301e9e6cabf2ae028d8ed4dacc7c09760449d1a865c41/68747470733a2f2f636f6465636f762e696f2f67682f7a656e73747275636b2f696d6167652f6272616e63682f312e782f67726170682f62616467652e7376673f746f6b656e3d4d424b5343504f365535)](https://codecov.io/gh/zenstruck/image)

Image file wrapper to provide image-specific [metadata](#usage), generic [transformations](#transformations), and [ThumbHash generator](#thumbhash).

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

[](#installation)

```
composer require zenstruck/image
```

Usage
-----

[](#usage)

Note

`Zenstruck\ImageFileInfo` extends `\SplFileInfo`.

```
use Zenstruck\ImageFileInfo;

$image = ImageFileInfo::wrap('some/local.jpg'); // create from local file
$image = ImageFileInfo::from($resource); // create from resource/stream (in a temp file)

// dimensional information
$image->dimensions()->height(); // int
$image->dimensions()->width(); // int
$image->dimensions()->aspectRatio(); // float
$image->dimensions()->pixels(); // int
$image->dimensions()->isSquare(); // bool
$image->dimensions()->isLandscape(); // bool
$image->dimensions()->isPortrait(); // bool

// other metadata
$image->mimeType(); // string (ie "image/jpeg")
$image->guessExtension(); // string - the extension if available or guess from mime-type
$image->iptc(); // array - IPTC data (if the image supports)
$image->exif(); // array - EXIF data (if the image supports)

// utility
$image->refresh(); // self - clear any cached metadata
$image->delete(); // void - delete the image file

// access any \SplFileInfo methods
$image->getMTime();
```

Note

Images created with `ImageFileInfo::from()` are created in unique temporary files and deleted at the end of the script.

### Transformations

[](#transformations)

The following transformers are available:

- [GD](https://www.php.net/manual/en/book.image.php)
- [Imagick](https://www.php.net/manual/en/book.imagick.php)
- [intervention\\image](https://github.com/Intervention/image)
- [imagine\\imagine](https://github.com/php-imagine/Imagine)
- [spatie\\image](https://github.com/spatie/image)

To use the desired transformer, type-hint the first parameter of the callable passed to `Zenstruck\ImageFileInfo::transform()` with the desired transformer's *image object*:

- **GD**: `\GdImage`
- **Imagick**: `\Imagick`
- **intervention\\image**: `Intervention\Image\Image`
- **imagine\\imagine**: `Imagine\Image\ImageInterface`
- **spatie\\image**: `Spatie\Image\Image`

Note

The return value of the callable must be the same as the passed parameter.

The following example uses `\GdImage` but any of the above type-hints can be used.

```
/** @var Zenstruck\ImageFileInfo $image */

$resized = $image->transform(function(\GdImage $image): \GdImage {
    // perform desired manipulations...

    return $image;
}); // a new temporary Zenstruck\ImageFileInfo instance (deleted at the end of the script)

// configure the format
$resized = $image->transform(
    function(\GdImage $image): \GdImage {
        // perform desired manipulations...

        return $image;
    },
    ['format' => 'png']
);

// configure the path for the created file
$resized = $image->transform(
    function(\GdImage $image): \GdImage {
        // perform desired manipulations...

        return $image;
    },
    ['output' => 'path/to/file.jpg']
);
```

#### Transform "In Place"

[](#transform-in-place)

```
/** @var Zenstruck\ImageFileInfo $image */

$resized = $image->transformInPlace(function(\GdImage $image): \GdImage {
    // perform desired manipulations...

    return $image;
}); // overwrites the original image file
```

#### Filter Objects

[](#filter-objects)

Both *Imagine* and *Intervention* have the concept of *filters*. These are objects that can be passed directly to `transform()` and `transformInPlace()`:

```
/** @var Imagine\Filter\FilterInterface $imagineFilter */
/** @var Intervention\Image\Filters\FilterInterface|Intervention\Image\Interfaces\ModifierInterface $interventionFilter */
/** @var Zenstruck\ImageFileInfo $image */

$transformed = $image->transform($imagineFilter);
$transformed = $image->transform($interventionFilter);

$image->transformInPlace($imagineFilter);
$image->transformInPlace($interventionFilter);
```

##### Custom Filter Objects

[](#custom-filter-objects)

Because `transform()` and `transformInPlace()` accept any callable, you can wrap complex transformations into invokable *filter objects*:

```
class GreyscaleThumbnail
{
    public function __construct(private int $width, private int $height)
    {
    }

    public function __invoke(\GdImage $image): \GdImage
    {
        // greyscale and resize to $this->width/$this->height

        return $image;
    }
}
```

To use, pass a new instance to `transform()` or `transformInPlace()`:

```
/** @var Zenstruck\ImageFileInfo $image */

$thumbnail = $image->transform(new GreyscaleThumbnail(200, 200));

$image->transformInPlace(new GreyscaleThumbnail(200, 200));
```

#### Transformation Object

[](#transformation-object)

`Zenstruck\ImageFileInfo::as()` returns a new instance of the desired transformation library's *image object*:

```
use Imagine\Image\ImageInterface;

/** @var Zenstruck\ImageFileInfo $image */

$image->as(ImageInterface::class); // ImageInterface object for this image
$image->as(\Imagick::class); // \Imagick object for this image
```

### ThumbHash

[](#thumbhash)

> A very compact representation of an image placeholder. Store it inline with your data and show it while the real image is loading for a smoother loading experience.
>
> **-- [evanw.github.io/thumbhash](https://evanw.github.io/thumbhash/)**

Note

[`srwiez/thumbhash`](https://github.com/SRWieZ/thumbhash) is required for this feature (install with `composer require srwiez/thumbhash`).

Note

[`Imagick`](https://www.php.net/manual/en/book.imagick.php) is required for this feature.

#### Generate from Image

[](#generate-from-image)

```
use Zenstruck\Image\Hash\ThumbHash;

/** @var Zenstruck\ImageFileInfo $image */

$thumbHash = $image->thumbHash(); // ThumbHash

$thumbHash->dataUri(); // string - the ThumbHash as a data-uri
$thumbHash->approximateAspectRatio(); // float - the approximate aspect ratio
$thumbHash->key(); // string - small string representation that can be cached/stored in a database
```

Caution

Generating from an image can be slow depending on the size of the source image. It is recommended to cache the data-uri and/or key for subsequent requests of the same ThumbHash image.

#### Generate from Key

[](#generate-from-key)

When generating from an image, the `ThumbHash::key()` method returns a small string that can be stored for later use. This key can be used to generate the ThumbHash without needing to re-process the image.

```
use Zenstruck\Image\Hash\ThumbHash;

/** @var string $key */

$thumbHash = ThumbHash::fromKey($key); // ThumbHash

$thumbHash->dataUri(); // string - the ThumbHash as a data-uri
$thumbHash->approximateAspectRatio(); // float - the approximate aspect ratio
```

###  Health Score

50

—

FairBetter than 96% of packages

Maintenance78

Regular maintenance activity

Popularity39

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity56

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 ~140 days

Recently: every ~278 days

Total

9

Last Release

92d ago

Major Versions

v0.5.0 → v1.0.02024-03-21

### Community

Maintainers

![](https://www.gravatar.com/avatar/707369cc916e0ea1aacbf077dcba464f611cef879f024d8944311a54a15224b3?d=identicon)[kbond](/maintainers/kbond)

---

Top Contributors

[![kbond](https://avatars.githubusercontent.com/u/127811?v=4)](https://github.com/kbond "kbond (56 commits)")

---

Tags

imagegdimagickmanipulationimaginetransformationintervention

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[league/glide

Wonderfully easy on-demand image manipulation library with an HTTP based API.

2.6k51.2M116](/packages/league-glide)[liip/imagine-bundle

This bundle provides an image manipulation abstraction toolkit for Symfony-based projects.

1.7k38.3M217](/packages/liip-imagine-bundle)[folklore/image

Image manipulation library for Laravel 5 based on Imagine and inspired by Croppa for easy url based manipulation

270248.2k5](/packages/folklore-image)[admad/cakephp-glide

CakePHP plugin for using Glide image manipulation library.

34160.7k1](/packages/admad-cakephp-glide)[talesoft/phim

An image and color manipulation and processing library for PHP

2958.2k](/packages/talesoft-phim)

PHPackages © 2026

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