README

提供图像特定 元数据、通用 变换 和 ThumbHash 生成器 的图像文件包装器。

安装

composer require zenstruck/image

使用方法

注意

Zenstruck\ImageFileInfo 扩展 \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();

注意

使用 ImageFileInfo::from() 创建的图像将在独特的临时文件中创建，并在脚本结束时删除。

变换

以下变换器可用

• GD
• Imagick
• intervention\image
• imagine\imagine
• spatie\image

要使用所需的变换器，请使用所需变换器的 图像对象 对 Zenstruck\ImageFileInfo::transform() 传递的可调用函数的第一个参数进行类型提示

• GD: \GdImage
• Imagick: \Imagick
• intervention\image: Intervention\Image\Image
• imagine\imagine: Imagine\Image\ImageInterface
• spatie\image: Spatie\Image\Image

注意

可调用函数的返回值必须与传递的参数相同。

以下示例使用 \GdImage，但可以使用上述任何类型提示。

/** @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']
);

就地变换

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

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

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

过滤器对象

Imagine 和 Intervention 都有 过滤器 的概念。这些可以直接传递给 transform() 和 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);

自定义过滤器对象

因为 transform() 和 transformInPlace() 接受任何可调用函数，所以可以将复杂的变换包装成可调用的 过滤器对象

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;
    }
}

要使用，将新实例传递给 transform() 或 transformInPlace()

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

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

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

变换对象

Zenstruck\ImageFileInfo::as() 返回所需变换库的 图像对象 的新实例

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

图像占位符的非常紧凑的表示。将其与您的数据一起存储，并在真实图像加载时显示，以获得更平滑的加载体验。

-- evanw.github.io/thumbhash

注意

需要 srwiez/thumbhash 来实现此功能（使用 composer require srwiez/thumbhash 安装）。

注意

需要 Imagick 来实现此功能。

从图像生成

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

注意

根据源图像的大小，从图像生成可能很慢。建议对相同 ThumbHash 图像的后续请求缓存数据-uri 和/或密钥。

从密钥生成

在从图像生成时，ThumbHash::key() 方法返回一个小的字符串，可以存储以供以后使用。此密钥可用于生成 ThumbHash，而无需重新处理图像。

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