zenstruck/image

Image file wrapper with generic transformation support.

v1.0.0 2024-03-21 22:30 UTC

Requires

• php: >=8.0
• symfony/polyfill-php81: ^1.26
• zenstruck/temp-file: ^1.0

Requires (Dev)

• imagine/imagine: ^1.3
• intervention/image: ^2.7|^3.0
• phpstan/phpstan: ^1.4
• phpunit/phpunit: ^9.5.0
• psr/container: ^1.0|^2.0
• spatie/image: ^2.0|^3.2
• srwiez/thumbhash: ^1.2
• symfony/phpunit-bridge: ^6.1|^7.0
• symfony/var-dumper: ^5.4|^6.0|^7.0

Suggests

• imagine/imagine: To use the Imagine image transformer.
• intervention/image: To use the Intervention image transformer.
• srwiez/thumbhash: To generate ThumbHashes.

MIT

• Kevin Bond

• image
• imagine
• gd
• imagick
• manipulation
• transformation
• intervention

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