图片

在现代 Web 应用开发中，高效的图片处理是提升用户体验和优化网站性能的关键因素。虽然大多数企业级应用会选择使用 CDN 服务来处理图片资源，但这往往会带来不必要的额外成本。为了解决这一问题，专业版实现了一套功能强大且易于使用的本地图片处理解决方案，让开发者能够轻松实现图片元数据提取、水印添加、文字叠加、尺寸调整以及动态图片响应等高级功能。

适用范围说明

本章节介绍的图片处理功能专为本地图片存储设计。如果您的应用使用 OSS（对象存储服务）或其他云存储解决方案，请参考相应的云服务文档获取图片处理方法。

环境配置

系统依赖

图片处理功能依赖于以下图像处理扩展之一，请确保您的服务器已安装并启用：

• GD 库 （默认选项）：PHP 内置的图像处理库，适用于大多数基础图像处理需求
• Imagick ：ImageMagick 的 PHP 扩展，提供更强大的图像处理能力和更广泛的格式支持 如果您的系统尚未安装这些扩展，请先完成安装配置。

环境变量配置

在项目根目录的 .env 文件中添加以下配置项（如已存在则无需重复添加）：

# 默认处理图片的驱动 GD 扩展
CATCH_IMAGE_DRIVER=gd
# 默认从 uploads 磁盘读取
CATCH_IMAGE_READ_FROM=uploads

配置文件

在 config/catch.php 配置文件添加下面的配置，如果已有，请忽略

return [
    /*
   |--------------------------------------------------------------------------
   | 图片处理配置
   |
   | 控制图片处理的核心参数和默认行为
   |--------------------------------------------------------------------------
   */
    'image' => [
        // 图片处理驱动，从环境变量获取，默认使用GD库
        'driver' => env('CATCH_IMAGE_DRIVER', 'gd'),

        // 图片处理附加选项，可根据需要扩展
        'options' => [
            // 在此添加自定义选项
        ],

        /**
         * 默认读取图片的存储磁盘
         * 此设置决定了图片处理功能默认从哪个存储磁盘读取源图片
         */
        'read_from' => env('CATCH_IMAGE_READ_FROM', 'uploads'),
    ],
]

图片元数据

图片元数据功能允许您快速获取图片的各种属性信息，如尺寸、文件大小、MIME 类型等，这对于图片管理和验证非常有用。

use Catch\Support\Image\Image;

// 指定图片的相对路径（相对于默认存储磁盘，通常是uploads）
$path = 'avatars/example.jpg';

// 获取图片的完整元数据
$metadata = Image::of($path)
    ->meta()
    ->data();

// 输出结果示例
/*
[
    "filename" => "example.jpg",
    "size" => "1.2 MB",
    "size_bytes" => 1258291,
    "datetime" => "2023-06-15 14:32:47",
    "width" => 1920,
    "height" => 1080,
    "mimetype" => "image/jpeg"
]
*/

实际应用场景

• 图片验证 ：在上传前检查图片尺寸是否符合要求
• 存储优化 ：根据图片大小决定是否需要压缩处理
• 前端展示 ：获取图片尺寸以优化页面布局
• 图片分类 ：根据图片类型和大小进行自动分类

图片水印

水印功能允许您在图片上叠加另一张图片作为水印，并提供丰富的位置控制和透明度调整选项，适用于版权保护、品牌展示等场景。

可用方法

图片水印功能允许您在图片上添加水印图片，并提供多种方法来控制水印的位置、透明度等属性。以下是所有可用的方法：

位置控制方法

这些方法用于设置水印在图片上的位置：

方法	描述
bottom()	将水印放置在图片底部中央
bottomLeft()	将水印放置在图片左下角
bottomRight()	将水印放置在图片右下角
center()	将水印放置在图片中央
top()	将水印放置在图片顶部
topLeft()	将水印放置在图片左上角
topRight()	将水印放置在图片右上角
right()	将水印放置在图片右侧
left()	将水印放置在图片左侧

偏移与透明度控制

方法	描述
offset(int $x, int $y)	设置水印的 X 和 Y 轴偏移量
opacity(int $opacity)	设置水印的透明度，范围为 0-100（0 为完全透明，100 为完全不透明）

保存与自定义处理

方法	描述
save(string $path, ?string $disk = null, array $options = [])	保存添加水印后的图片到指定路径，可选择指定磁盘和其他选项
saving(Closure $saving)	设置一个自定义的保存处理闭包函数

使用示例

// 图片的相对地址，默认使用 uploads 磁盘
$path = 'avatars/5fi5kxDVbd7NGhzY4b0NphYMa5Tg5lWDnBRjqhxU.jpg';

// 水印图片，绝对路径
$waterImage = \Illuminate\Support\Facades\Storage::disk('uploads')->path('water.jpg');

/ 创建带水印的图片并保存
Image::of($sourcePath)
    ->watermark($watermarkPath) // 设置水印图片
    ->bottomRight() // 放置在右下角
    ->offset(20, 20) // 距离边缘20像素
    ->opacity(40) // 设置40%的透明度
    ->saving(function ($watermark, $image) {
        // 在添加水印前对原图进行额外处理
        $image->brightness(5)->contrast(10);
    })
    ->save(
        'products/product-display-watermarked.jpg', // 保存路径
        'public', // 保存到public磁盘
        ['quality' => 85] // 设置85%的图片质量
    );

WARNING

透明度参数说明 透明度参数 opacity 的有效范围为 0-100：

• 0 表示完全透明（水印不可见）
• 100 表示完全不透明
• 推荐值：20-60，根据水印图片和背景复杂度调整设置超出范围的值将导致 InvalidArgumentException

图片文字

图片文字功能允许您在图片上添加自定义文本，支持丰富的字体、颜色、位置和特效设置，适用于版权声明、说明文字、营销文案等多种场景。

基本用法

use Catch\Support\Image\Image;

// 在图片上添加简单文字
Image::of('events/conference.jpg')
    ->text('2023年技术峰会') // 设置文字内容
    ->fontsize(28) // 设置字体大小
    ->color('#FFFFFF') // 设置白色文字
    ->alignCenter() // 水平居中
    ->valignBottom() // 垂直靠底部
    ->offset(0, 30) // 距底部30像素
    ->save('events/conference-titled.jpg');

保存到存储盘

将图像保存到 Laravel 存储盘：

Image::of('path/to/image.jpg')
    ->text('你好，世界！')
    ->fontsize(24)
    ->color('#FF0000')
    ->save('output.jpg', 'public');

高级定制

实现复杂文本格式，如添加描边、旋转文本或自动换行：

Image::of('path/to/image.jpg')
    ->text('这是一段很长的文本，将自动换行。')
    ->fontsize(20)
    ->ttf('path/to/font.ttf')
    ->color('#FFFFFF')
    ->stroke('#000000', 2)
    ->alignCenter()
    ->valignTop()
    ->angle(45)
    ->wrap(200)
    ->save('path/to/output.jpg');

自定义处理

使用 saving 方法通过闭包进行额外的图像处理：

Image::of('path/to/image.jpg')
    ->text('这是一段很长的文本，将自动换行。')
    ->fontsize(30)
    ->saving(function ($warpText, $image) {
        $image->brightness(10)->contrast(20);
    })
    ->save('path/to/output.jpg');

方法

方法名	参数	描述	返回值
offset	int $x = 0, int $y = 0	设置文本相对于图像左上角的 X 和 Y 偏移（像素）	static
save	string $path, ?string $disk = null, array $options = []	应用文本配置并保存图像，可指定存储盘	ImageInterface
fontsize	?float $size	设置字体大小（点）	static
ttf	?string $ttfFile	设置自定义 TTF 字体文件路径	static
color	mixed $color	设置文本颜色（例如十六进制、RGB 数组）	static
stroke	?string $stroke, int $width = 1	设置文本描边颜色和宽度（像素）	static
alignLeft	-	设置水平左对齐	static
alignRight	-	设置水平右对齐	static
alignCenter	-	设置水平居中对齐	static
valignTop	-	设置垂直顶部对齐	static
valignBottom	-	设置垂直底部对齐	static
valignMiddle	-	设置垂直居中对齐	static
lineHeight	float $lineHeight	设置多行文本的行高倍数（默认 1.25）	static
angle	?float $angle	设置文本顺时针旋转角度（度）	static
wrap	?int $wrap	设置文本自动换行的最大宽度（像素）	static
center	-	水平居中文本（基于图像宽度）	static
middle	-	垂直居中文本（基于图像高度）	static
saving	Closure $callback	设置保存前的自定义图像处理闭包	static

示例

以下是综合示例，展示多种功能：

Image::of('path/to/image.jpg')
    ->text('欢迎体验图像处理！')
    ->fontsize(32)
    ->ttf('fonts/SimSun.ttf')
    ->color('#333333')
    ->stroke('#FFFFFF', 2)
    ->alignCenter()
    ->valignMiddle()
    ->lineHeight(1.5)
    ->angle(30)
    ->wrap(300)
    ->saving(function ($warpText, $image) {
        $image->resize(800, null, function ($constraint) {
            $constraint->aspectRatio();
        });
    })
    ->save('output.jpg', 'public', ['quality' => 90]);

此示例：

• 在 input.jpg 上添加文本“欢迎体验图像处理！”。
• 使用 32 点宋体字体，深灰色文本，白色描边（2 像素宽）。
• 水平和垂直居中。
• 设置行高为 1.5，旋转 30 度。
• 在 300 像素宽度内自动换行。
• 将图像宽度调整为 800 像素，保持纵横比。
• 以 90% 质量保存到 public 存储盘的 output.jpg。

错误处理

• 确保源图像路径 $path 存在。
• 若提供 TTF 字体文件，需确保文件存在。
• 使用存储盘时，需正确配置存储盘。
• 无效的对齐方式或颜色值可能导致 Intervention Image 库抛出异常。

图片尺寸

在日常开发中，我们经常需要对图片进行尺寸调整，以适应不同的显示需求。专业版提供了强大的图片尺寸调整功能，支持多种调整方式，如等比例缩放、覆盖模式、填充模式等。

基本用法

use Catch\Support\Image\Image;

// 图片的相对地址，默认使用 uploads 磁盘
$path = 'avatars/example.jpg';

// 调整图片尺寸并保存
Image::of($path)
    ->resize(800, 600) // 设置目标宽度和高度
    ->scale() // 使用等比例缩放模式
    ->save('resized/example.jpg'); // 保存到指定路径

调整方法

图片尺寸调整类支持多种调整方法，您可以根据需要选择合适的方式：

方法	描述
scale()	等比例缩放图片，保持原始比例
scaleDown()	等比例缩小图片（不会放大），保持原始比例
cover(string $position = 'center')	覆盖模式调整图片尺寸，可能会裁剪部分图片
coverDown(string $position = 'center')	覆盖模式调整图片尺寸（不会放大），可能会裁剪部分图片
pad(mixed $background = 'ffffff', string $position = 'center')	填充模式调整图片尺寸，会在图片周围添加背景色
contain(mixed $background = 'ffffff', string $position = 'center')	包含模式调整图片尺寸，会保持图片比例并添加背景色
crop(int $offset_x = 0, int $offset_y = 0, mixed $background = 'ffffff', string $position = 'top-left')	裁剪图片
resizeCanvas(mixed $background = 'ffffff', string $position = 'center')	调整画布大小
resizeCanvasRelative(mixed $background = 'ffffff', string $position = 'center')	相对调整画布大小
trim(int $tolerance = 0)	裁剪图片边缘
disallowOriginSize()	不允许超过原始图片尺寸

位置参数

多个方法支持位置参数，可用的位置值包括：

• center：中心位置
• top：顶部中心
• top-left：左上角
• top-right：右上角
• bottom：底部中心
• bottom-left：左下角
• bottom-right：右下角
• left：左侧中心
• right：右侧中心

保存图片

调整图片尺寸后，您可以使用 save 方法将图片保存到指定路径：

Image::of('avatars/example.jpg')
    ->resize(800, 600)
    ->scale()
    ->save(
        'resized/example.jpg', // 保存路径
        'public', // 可选，指定存储磁盘
        ['quality' => 90] // 可选，保存选项
    );

自定义处理

您可以使用 saving 方法设置一个自定义的保存处理闭包函数：

Image::of('avatars/example.jpg')
    ->resize(800, 600)
    ->scale()
    ->saving(function ($resize, $image) {
        // 在保存前对图片进行额外处理
        $image->greyscale();
    })
    ->save('resized/example.jpg');

使用示例

等比例缩放

Image::of('avatars/example.jpg')
    ->resize(800, null) // 只设置宽度，高度自动按比例调整
    ->scale()
    ->save('resized/example.jpg');

覆盖模式（裁剪适应）

Image::of('avatars/example.jpg')
    ->resize(300, 300) // 固定宽高
    ->cover('center') // 从中心裁剪
    ->save('resized/example_cover.jpg');

填充模式（添加背景）

Image::of('avatars/example.jpg')
    ->resize(300, 300)
    ->pad('f0f0f0') // 使用浅灰色背景
    ->save('resized/example_pad.jpg');

裁剪图片

Image::of('avatars/example.jpg')
    ->resize(300, 200)
    ->crop(50, 50) // 从左上角偏移 50px
    ->save('resized/example_crop.jpg');

裁剪边缘

Image::of('avatars/example.jpg')
    ->resize(null, null) // 保持原始尺寸
    ->trim(10) // 裁剪边缘，容差值为 10
    ->save('resized/example_trim.jpg');

注意事项

• 如果不指定宽度或高度（设为 null），将保持原始图片的相应尺寸。
• 使用 scaleDown 或 coverDown 方法可以防止图片被放大，只会缩小图片。
• 背景色参数可以使用十六进制颜色代码（如 'ffffff'）或其他 Intervention Image 支持的颜色格式。
• 确保目标保存路径所在的目录已存在且有写入权限。

图片响应

日常中，在管理图片的时候，我们需要对图片进行裁剪压缩，减小带宽的压力。一般都是操作原图，然后保存成小图。无法动态的响应图片大小。专业版提供了一个非常简单的操作来实现。

图片响应类是专业版提供的一个用于处理图片输出的工具类，它允许您以不同的格式响应图片，并支持设置图片的宽度、高度和质量等参数。

基本用法

use Catch\Support\Image\Image;

Route::get('image', function () {
    // 图片的相对地址，默认使用 uploads 磁盘
    $path = 'avatars/example.jpg';

    return Image::of($path)
        ->response() // 调用响应
        ->width(200) // 设置宽度
        ->height(150) // 设置高度（可选）
        ->quality(80) // 设置质量
        ->webp(); // 输出为WEBP格式
});

支持的图片格式

图片响应类支持多种常见的图片格式输出，您可以根据需要选择合适的格式：

方法	描述
webp()	将图片以 WEBP 格式输出，通常具有更好的压缩率
png()	将图片以 PNG 格式输出，适合需要透明背景的图片
jpeg()	将图片以 JPEG 格式输出，适合照片等复杂图像
gif()	将图片以 GIF 格式输出，支持动画效果

动态调用其他格式

除了上述预定义的格式方法外，您还可以通过动态方法调用其他支持的格式：

return Image::of($path)
    ->response()
    ->width(300)
    ->avif(); // 使用AVIF格式

参数设置

设置图片尺寸

return Image::of($path)
    ->response()
    ->width(200) // 设置宽度为200像素
    ->height(150) // 设置高度为150像素
    ->png();

如果只设置宽度或高度中的一个，图片将按比例缩放。

设置图片质量

return Image::of($path)
    ->response()
    ->quality(75) // 设置质量为75%（范围0-100）
    ->jpeg();

质量参数范围为 0-100，值越高图片质量越好，但文件大小也越大。

切换磁盘

您可以指定从哪个磁盘读取图片：

return Image::of('avatars/example.jpg')
    ->response()
    ->disk('custom_disk') // 从自定义磁盘读取图片
    ->width(200)
    ->png();

磁盘配置在 config/filesystem.php 的 disks 部分定义。

动态参数响应

支持类似 OSS 处理的动态处理，目前支持的 宽高和质量三个

Route::get('image', function () {
    return Image::of('avatars/5fi5kxDVbd7NGhzY4b0NphYMa5Tg5lWDnBRjqhxU.jpg')
        ->response()
        ->disk('some_your_disk')
        ->width(request()->get('width'))
        ->height(request()->get('height'))
        ->quality(request()->get('quality'))
        ->png();
})

访问图片的地址就变成这样

/image?width=100&height=50&quality=100

支持输出图片格式

• png;
• jpeg;
• gif
• avif
• webp