图像处理

简介

Laravel 提供了流畅的图像处理 API，让你可以使用框架中一贯富有表现力的约定来调整图像大小、裁剪、编码和存储图像。Laravel 的图像功能由 Intervention Image 提供支持，并支持 GD 和 Imagick PHP 扩展。

处理上传文件、存储在 Laravel 文件系统磁盘中的文件、本地文件、远程 URL 或原始图像字节时，都可以使用图像 API：

use Illuminate\Support\Facades\Image;

$path = Image::fromStorage('avatars/photo.jpg', 'public')
    ->cover(400, 400)
    ->toWebp()
    ->quality(80)
    ->storePublicly('avatars', 'public');

WARNING

图像处理可能会消耗大量 CPU 和内存。对于大型图像处理工作负载，建议使用队列任务处理，避免在接收上传文件的 HTTP 请求期间执行。

安装

使用 Laravel 的图像处理功能之前，请通过 Composer 安装 Intervention Image 包：

composer require intervention/image:^4.0

你还应确保 PHP 安装了 GD 或 Imagick 扩展，具体取决于应用所使用的驱动。

配置

Laravel 的图像配置文件位于 config/images.php。如果应用中没有 images 配置文件，可以使用 config:publish Artisan 命令发布该文件：

php artisan config:publish images

你可以在图像配置文件中指定应用的默认图像驱动，也可以使用 IMAGE_DRIVER 环境变量进行指定。支持的驱动为 gd 和 imagick：

IMAGE_DRIVER=imagick

读取图像

Image facade 提供了多种从常见来源读取图像的方法。图像内容采用延迟加载，因此通常会在处理图像或请求其字节内容时才读取来源数据。

上传文件

你可以使用 image 方法从传入请求中获取上传的图像。该方法会为上传文件返回一个 Illuminate\Image\Image 实例；如果文件不存在，则返回 null：

use Illuminate\Http\Request;

Route::post('/avatar', function (Request $request) {
    $request->validate(['avatar' => ['required', 'image']]);

    $path = $request->image('avatar')
        ->cover(400, 400)
        ->toWebp()
        ->storePublicly('avatars', 'public');

    // ...
});

或者，你也可以使用 fromUpload 方法从 Illuminate\Http\UploadedFile 实例创建图像实例：

use Illuminate\Support\Facades\Image;

$image = Image::fromUpload($request->file('avatar'));

从上传文件创建图像后，可以使用 file 方法获取底层的上传文件：

$file = $image->file();

存储文件

你可以使用 fromStorage 方法，从应用任一文件系统磁盘中存储的文件创建图像实例。第一个参数是文件路径，第二个参数是磁盘名称：

use Illuminate\Support\Facades\Image;

$image = Image::fromStorage('avatars/photo.jpg', disk: 'public');

你也可以使用 image 方法，直接从文件系统磁盘实例创建图像实例：

use Illuminate\Support\Facades\Storage;

$image = Storage::disk('public')->image('avatars/photo.jpg');

其他来源

Image facade 还提供了从原始字节、本地文件路径、远程 URL 和 Base64 编码字符串创建图像实例的方法：

use Illuminate\Support\Facades\Image;

$image = Image::fromBytes($contents);
$image = Image::fromBase64($base64);
$image = Image::fromPath(storage_path('app/avatars/photo.jpg'));
$image = Image::fromUrl('https://example.com/photo.jpg');

处理图像

图像实例是不可变的。每个处理方法都会返回一个新的图像实例，并将相应转换追加到处理管道中，因此你可以流畅地链式调用这些方法：

$image = $request->image('avatar')
    ->orient()
    ->cover(400, 400)
    ->sharpen(10);

各项转换会按照加入图像管道的顺序依次处理，图像只会在最后编码一次。

调整图像大小

resize 方法会将图像调整为指定尺寸。你可以同时提供宽度和高度，也可以使用命名参数只提供其中一个尺寸：

$image = $image->resize(800, 600);
$image = $image->resize(width: 800);
$image = $image->resize(height: 600);

scale 方法会按比例缩小图像，使其适应指定尺寸。该方法不会放大图像：

$image = $image->scale(800, 600);
$image = $image->scale(width: 800);
$image = $image->scale(height: 600);

cover 方法会调整并裁剪图像，使其完全覆盖指定尺寸：

$image = $image->cover(400, 400);

contain 方法会调整图像大小，使其适应指定尺寸，同时保留完整图像。如有需要，空白区域会使用可选的背景颜色填充：

$image = $image->contain(400, 400);
$image = $image->contain(400, 400, '#ffffff');
$image = $image->contain(400, 400, 'dominant');

你可以将 dominant 指定为背景颜色，以使用图像的主色填充空白区域。

你可以使用 crop 方法裁剪图像。前两个参数是所需的宽度和高度，可选的第三、第四个参数用于指定裁剪的 x 和 y 坐标：

$image = $image->crop(300, 200);
$image = $image->crop(300, 200, x: 50, y: 25);

其他转换

Laravel 还提供了多种其他图像转换方法：

$image = $image->orient();
$image = $image->rotate(90);
$image = $image->rotate(90, '#ffffff');
$image = $image->rotate(90, 'dominant');
$image = $image->blur(5);
$image = $image->grayscale();
$image = $image->sharpen(10);
$image = $image->flipVertically();
$image = $image->flipHorizontally();

orient 方法会根据图像的 EXIF 方向数据旋转图像。rotate 方法会按给定角度顺时针旋转图像，并接受可选的背景颜色。blur 和 sharpen 方法接受 0 到 100 之间的值。

条件转换

图像实例支持 Laravel 的 Conditionable trait，你可以使用 when 和 unless 方法有条件地应用转换：

$image = $request->image('avatar')
    ->when($request->boolean('crop'), fn ($image) => $image->cover(400, 400))
    ->unless($request->boolean('preserve_format'), fn ($image) => $image->toWebp());

编码图像

默认情况下，处理后的图像会使用原始格式进行编码。你也可以在获取或存储图像之前，将其转换为其他受支持的格式：

$image = $image->toWebp();
$image = $image->toJpg();
$image = $image->toJpeg();
$image = $image->toPng();
$image = $image->toGif();
$image = $image->toAvif();
$image = $image->toBmp();

你可以使用 quality 方法设置输出质量。质量值会限制在 1 到 100 之间：

$image = $image->toWebp()->quality(80);

optimize 方法是一个便捷的快捷方式，可以将图像转换为指定格式并设置其质量。默认情况下，图像会优化为质量为 70 的 WebP 图像：

$image = $image->optimize();

$image = $image->optimize(format: 'jpg', quality: 85);

你可以将处理后的图像内容获取为字节字符串、Base64 编码字符串或数据 URI：

$bytes = $image->toBytes();
$base64 = $image->toBase64();
$dataUri = $image->toDataUri();

图像实例也可以转换为字符串，以获取处理后的字节内容：

$bytes = (string) $image;

存储图像

store 方法会将处理后的图像存储到应用的某个文件系统磁盘中。与上传文件一样，Laravel 会生成唯一文件名并返回存储路径。第二个参数可用于指定磁盘：

$path = $request->image('avatar')
    ->cover(400, 400)
    ->store(path: 'avatars');

$path = $request->image('avatar')
    ->cover(400, 400)
    ->store(path: 'avatars', disk: 's3');

你可以使用 storeAs 方法指定存储时使用的文件名：

$path = $request->image('avatar')
    ->cover(400, 400)
    ->storeAs(path: 'avatars', name: 'avatar.jpg', disk: 'public');

storePublicly 和 storePubliclyAs 方法会以 public 可见性存储图像：

$path = $request->image('avatar')
    ->cover(400, 400)
    ->storePublicly(path: 'avatars', disk: 'public');

$path = $request->image('avatar')
    ->cover(400, 400)
    ->storePubliclyAs(path: 'avatars', name: 'avatar.webp', disk: 'public');

如果图像无法存储，这些存储方法会返回 false。

检查图像

你可以使用以下方法获取图像的 MIME 类型、扩展名、尺寸、宽度、高度和主色：

$mimeType = $image->mimeType();
$extension = $image->extension();

[$width, $height] = $image->dimensions();
$width = $image->width();
$height = $image->height();

$dominantColor = $image->dominantColor();

这些方法作用于处理后的图像。例如，在 cover(400, 400) 之后调用 width 将返回 400。

图像驱动

自定义图像驱动

Laravel 的图像管理器扩展了 Laravel 的基础 Illuminate\Support\Manager 类。这意味着你可以使用图像管理器和 Image facade 上的 extend 方法注册自定义图像驱动。

自定义图像驱动应实现 Illuminate\Contracts\Image\Driver 接口。process 方法接收原始图像内容以及需要按顺序应用于图像的 Illuminate\Image\ImagePipeline，并应返回处理后的图像字节：

<?php

namespace App\Images;

use Illuminate\Contracts\Image\Driver;
use Illuminate\Image\ImagePipeline;

class VipsDriver implements Driver
{
    /**
     * 使用指定管道处理给定的图像内容。
     */
    public function process(string $contents, ImagePipeline $pipeline): string
    {
        // 应用管道中的转换和输出选项...

        return $contents;
    }

    /**
     * 注册转换处理程序。
     */
    public function transformUsing(string $transformation, callable $callback): static
    {
        // 存储处理程序，以便在处理管道时应用...

        return $this;
    }
}

NOTE

要进一步了解如何实现自定义图像驱动，可以查看框架内置的 Illuminate\Image\Drivers\InterventionDriver 类。

实现自定义驱动后，可以使用 Image facade 的 extend 方法进行注册。通常，应在 service provider 的 boot 方法中完成此操作：

use App\Images\VipsDriver;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Image;

/**
 * 引导所有应用服务。
 */
public function boot(): void
{
    Image::extend('vips', function (Application $app) {
        return new VipsDriver;
    });
}

注册驱动后，可以使用 using 方法将其用于特定图像：

$image = $request->image('avatar')
    ->using('vips')
    ->cover(400, 400);

你也可以使用应用 config/images.php 配置文件中的 default 选项或 IMAGE_DRIVER 环境变量，将自定义驱动配置为应用的默认图像驱动：

IMAGE_DRIVER=vips

自定义转换

应用和包可以通过创建实现 Illuminate\Contracts\Image\Transformation 契约的类来定义自定义转换。随后，可以使用 transform 方法将自定义转换添加到图像管道：

<?php

namespace App\Images\Transformations;

use Illuminate\Contracts\Image\Transformation;

class Pixelate implements Transformation
{
    public function __construct(
        public readonly int $size,
    ) {
        //
    }
}

接下来，使用 Image facade 的 transformUsing 方法为转换和驱动注册处理程序。通常，应在 service provider 的 boot 方法中完成此操作：

use App\Images\Transformations\Pixelate;
use Illuminate\Support\Facades\Image;
use Intervention\Image\Interfaces\ImageInterface;

Image::transformUsing('gd', Pixelate::class, function (ImageInterface $image, Pixelate $transformation) {
    return $image->pixelate($transformation->size);
});

注册转换处理程序后，就可以将该转换应用到图像：

use App\Images\Transformations\Pixelate;

$image = $request->image('avatar')
    ->transform(new Pixelate(12))
    ->store('avatars');