README

Image file wrapper to provide image-specific metadata, generic transformations, and ThumbHash generator.

Installation

composer require zenstruck/image

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

The following transformers are available:

• GD
• Imagick
• intervention\image
• imagine\imagine
• 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"

/** @var Zenstruck\ImageFileInfo $image */ $resized = $image->transformInPlace(function(\GdImage $image): \GdImage { // perform desired manipulations... return $image; }); // overwrites the original image file

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

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

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

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

Note

srwiez/thumbhash is required for this feature (install with composer require srwiez/thumbhash).

Note

Imagick is required for this feature.

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

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