turbo / image
基于claviska/simpleimage,支持图片圆角、载入gd resource
Requires
- php: >=5.6.0
- ext-gd: *
- league/color-extractor: 0.3.*
This package is auto-updated.
Last update: 2024-09-29 05:55:37 UTC
README
一个使图像处理尽可能简单的PHP类。
由Cory LaViska开发并维护。
如果这个项目让你再次爱上了PHP图像处理,请考虑小额捐赠以支持其开发。
概览
<?php try { // Create a new SimpleImage object $image = new \claviska\SimpleImage(); // Magic! ✨ $image ->fromFile('image.jpg') // load image.jpg ->autoOrient() // adjust orientation based on exif data ->resize(320, 200) // resize to 320x200 pixels ->flip('x') // flip horizontally ->colorize('DarkBlue') // tint dark blue ->border('black', 10) // add a 10 pixel black border ->radius(10) // add a 10 pixel border-radius ->overlay('watermark.png', 'bottom right') // add a watermark image ->toFile('new-image.png', 'image/png') // convert to PNG and save a copy to new-image.png ->toScreen(); // output to the screen // And much more! 💪 } catch(Exception $err) { // Handle errors echo $err->getMessage(); }
要求
- PHP 5.6+
- GD扩展
功能
- 支持读取、写入和转换GIF、JPEG、PNG、WEBP、BMP格式。
- 读取和写入文件、数据URI和图像字符串。
- 操作:裁剪、调整大小、叠加/水印、添加TTF文本
- 绘图:弧线、边框、点、椭圆、线条、多边形、矩形、圆角矩形
- 过滤器:模糊、亮化、着色、对比度、变暗、去饱和、边缘检测、浮雕、反转、透明度、像素化、棕褐色、锐化、素描
- 工具:颜色调整、调整颜色亮度/暗度、提取颜色
- 属性:EXIF数据、高度/宽度、MIME类型、方向
- 颜色参数可以是任何CSS颜色(例如
LightBlue
)、十六进制颜色或RGB(A)数组。 - 支持alpha透明度(GIF、PNG、WEBP)
- 链式方法
- 使用异常
- 使用Composer或手动(仅一个文件)加载
- 语义化版本控制
安装
使用Composer安装
composer require claviska/simpleimage
或手动包含库
<?php require 'src/claviska/SimpleImage.php';
关于
SimpleImage由Cory LaViska开发并维护。版权所有 A Beautiful Site, LLC。
欢迎贡献!如果您喜欢使用SimpleImage,尤其是在商业应用中,请考虑捐赠以支持其开发。
谢谢!🙌
许可证
根据MIT许可证许可。
API
神奇顺序
- 加载图像
- 操作图像
- 保存/输出图像
API技巧
- 星号(*)表示必需参数。
- 返回SimpleImage对象的方法定义为链式可用的。
- 您可以通过构造函数传递文件或数据URI来避免调用
fromFile
或fromDataUri
。 - 可以使用
$image::methodName()
或\claviska\SimpleImage::methodName()
调用静态方法。 - 颜色可以是CSS颜色(例如
white
)、十六进制字符串(例如#ffffff
)或RGBA数组。 - 当您传递CSS颜色或十六进制字符串时,可以将透明度传递给
normalizeColor
:white|0.25
加载器
fromDataUri($uri)
从数据URI加载图像。
$uri
* (字符串) - 数据URI。
返回一个SimpleImage对象。
fromFile($file)
从文件加载图像。
$file
* (字符串) - 要加载的图像文件。
返回一个SimpleImage对象。
fromNew($width, $height, $color)
创建一个新的图像。
$width
* (整数) - 图像的宽度。$height
* (整数) - 图像的高度。$color
(字符串|数组) - 新图像的填充颜色(默认为'transparent')。
返回一个SimpleImage对象。
fromString($string)
从字符串创建一个新的图像。
$string
* (字符串) - 作为字符串的原始图像数据。示例$string = file_get_contents('image.jpg');
返回一个SimpleImage对象。
保存器
toDataUri($mimeType, $quality)
生成数据URI。
$mimeType
(字符串) - 输出为图像格式的MIME类型(默认为原始MIME类型)。$quality
(int) - 图片质量百分比(默认100)。
返回一个包含数据URI的字符串。
toDownload($filename, $mimeType, $quality)
强制将图像下载到客户端机器。必须在向屏幕发送任何输出之前调用。
$filename
* (string) - 发送到客户端的文件名(不带路径)(例如'图像.jpeg')。$mimeType
(字符串) - 输出为图像格式的MIME类型(默认为原始MIME类型)。$quality
(int) - 图片质量百分比(默认100)。
返回一个SimpleImage对象。
toFile($file, $mimeType, $quality)
将图像写入文件。
$mimeType
(字符串) - 输出为图像格式的MIME类型(默认为原始MIME类型)。$quality
(int) - 图片质量百分比(默认100)。
返回一个SimpleImage对象。
toScreen($mimeType, $quality)
将图像输出到屏幕。必须在向屏幕发送任何输出之前调用。
$mimeType
(字符串) - 输出为图像格式的MIME类型(默认为原始MIME类型)。$quality
(int) - 图片质量百分比(默认100)。
返回一个SimpleImage对象。
toString($mimeType, $quality)
生成图像字符串。
$mimeType
(字符串) - 输出为图像格式的MIME类型(默认为原始MIME类型)。$quality
(int) - 图片质量百分比(默认100)。
返回一个SimpleImage对象。
工具
getAspectRatio()
获取图像的当前宽高比。
返回一个浮点数表示的宽高比。
getExif()
获取图像的EXIF数据。
返回一个包含EXIF数据的数组或如果不可用则返回null。
getHeight()
获取图像的当前高度。
返回一个整数表示的高度。
getMimeType()
获取已加载图像的MIME类型。
返回一个MIME类型字符串。
getOrientation()
获取图像的当前方向。
返回一个字符串:'横向', '纵向', 或 '正方形'
getResolution()
获取图像当前分辨率的DPI。
返回一个包含整数的数组:[0 => 96, 1 => 96]
getWidth()
获取图像的当前宽度。
返回一个整数表示的宽度。
操作
autoOrient()
根据EXIF数据旋转图像,使其方向正确。对于没有EXIF数据的图像调用此方法也是安全的(不会有任何更改)。返回一个SimpleImage对象。
bestFit($maxWidth, $maxHeight)
按比例调整图像大小,使其适合特定的宽度和高度。
$maxWidth
* (int) - 图像的最大宽度。$maxHeight
* (int) - 图像的最大高度。
返回一个SimpleImage对象。
crop($x1, $y1, $x2, $y2)
裁剪图像。
- $x1 - 左上角x坐标。
- $y1 - 左上角y坐标。
- $x2 - 右下角x坐标。
- $y2 - 右下角y坐标。
返回一个SimpleImage对象。
fitToHeight($height)
(已弃用)
按比例调整图像大小以适应特定高度。
此方法在3.2.2版本中已弃用,将在4.0版本中删除。请使用resize(null, $height)
代替。
$height
* (int) - 调整图像大小的目标高度。
返回一个SimpleImage对象。
fitToWidth($width)
(已弃用)
按比例调整图像大小以适应特定宽度。
此方法在3.2.2版本中已弃用,将在4.0版本中删除。请使用resize($width, null)
代替。
$width
* (int) - 调整图像大小的目标宽度。
返回一个SimpleImage对象。
flip($direction)
水平或垂直翻转图像。
$direction
* (string) - 翻转方向:x|y|both
返回一个SimpleImage对象。
maxColors($max, $dither)
将图像减少到最大颜色数。
$max
* (int) - 要使用的最大颜色数。$dither
(bool) - 是否使用抖动效果(默认true)。
返回一个SimpleImage对象。
overlay($overlay, $anchor, $opacity, $xOffset, $yOffset)
将一个图像放置在当前图像的上方。
$overlay
* (string|SimpleImage) - 要叠加的图像。这可以是文件名、数据URI或SimpleImage对象。$anchor
(string) - 锚点:'center', 'top', 'bottom', 'left', 'right', 'top left', 'top right', 'bottom left', 'bottom right'(默认'center')$opacity
(float) - 叠加的透明度级别 0-1(默认1)。$xOffset
(int) - 像素水平偏移(默认0)。$yOffset
(int) - 像素垂直偏移(默认0)。
返回一个SimpleImage对象。
resize($width, $height)
将图像调整到指定的尺寸。如果只指定了一个尺寸,图像将按比例调整。
$width
* (int) - 新图像的宽度。$height
* (int) - 新图像的高度。
返回一个SimpleImage对象。
resolution($res_x, $res_y)
更改图像的分辨率(DPI)。
$res_x
* (int) - 水平分辨率,以DPI为单位。$res_y
(int) - 垂直分辨率,以DPI为单位。
返回一个SimpleImage对象。
rotate($angle, $backgroundColor)
旋转图像。
$angle
* (int) - 旋转角度(-360 - 360)。$backgroundColor
(string|array) - 旋转后未覆盖区域的背景颜色(默认 'transparent')。
返回一个SimpleImage对象。
text($text, $options, &$boundary)
向图像添加文本。
$text*
(string) - 要添加的文本。$options
(array) - 选项数组。fontFile
* (string) - 要使用的TrueType(或兼容)字体文件。size
(int) - 字体大小(以像素为单位,默认 12)。color
(string|array) - 文本颜色(默认黑色)。anchor
(string) - 锚点:'center', 'top', 'bottom', 'left', 'right', 'top left', 'top right', 'bottom left', 'bottom right'(默认 'center')。xOffset
(int) - 水平偏移量(以像素为单位,默认 0)。yOffset
(int) - 垂直偏移量(以像素为单位,默认 0)。shadow
(array) - 文本阴影参数。x
* (int) - 像素水平偏移。y
* (int) - 像素垂直偏移。color
* (string|array) - 文本阴影颜色。
$boundary
(array) - 如果传递,此变量将包含包含文本坐标的数组:[x1, y1, x2, y2, width, height]。这可以用于在文本添加到图像后计算文本的位置。
返回一个SimpleImage对象。
thumbnail($width, $height, $anchor)
创建缩略图图像。此函数尝试将图像调整到提供的尺寸,然后裁剪剩余的溢出部分以强制达到所需的大小。适用于生成缩略图。
$width
* (int) - 缩略图宽度。$height
* (int) - 缩略图高度。$anchor
(string) - 锚点:'center', 'top', 'bottom', 'left', 'right', 'top left', 'top right', 'bottom left', 'bottom right'(默认 'center')。
返回一个SimpleImage对象。
绘图
arc($x, $y, $width, $height, $start, $end, $color, $thickness)
绘制弧线。
$x
* (int) - 弧线中心的x坐标。$y
* (int) - 弧线中心的y坐标。$width
* (int) - 弧线的宽度。$height
* (int) - 弧线的高度。$start
* (int) - 弧线开始角度(度)。$end
* (int) - 弧线结束角度(度)。$color
* (string|array) - 弧线颜色。$thickness
(int|string) - 线条粗细(以像素为单位)或 'filled'(默认 1)。
返回一个SimpleImage对象。
border($color, $thickness)
在图像周围绘制边框。
$color
* (string|array) - 边框颜色。$thickness
(int) - 边框厚度(默认 1)。
返回一个SimpleImage对象。
dot($x, $y, $color)
绘制单个像素点。
$x
* (int) - 点的x坐标。$y
* (int) - 点的y坐标。$color
* (string|array) - 点的颜色。
返回一个SimpleImage对象。
ellipse($x, $y, $width, $height, $color, $thickness)
绘制椭圆。
$x
* (int) - 中心的x坐标。$y
* (int) - 中心的y坐标。$width
* (int) - 椭圆的宽度。$height
* (int) - 椭圆的高度。$color
(字符串|数组)- 椭圆颜色。$thickness
(int|string) - 线条粗细(以像素为单位)或 'filled'(默认 1)。
返回一个SimpleImage对象。
fill($color)
使用纯色填充图像。
$color
(字符串|数组)- 填充颜色。
返回一个SimpleImage对象。
line($x1, $y1, $x2, $y2, $color, $thickness)
绘制线条。
$x1
(整数)- 第一个点的x坐标。$y1
(整数)- 第一个点的y坐标。$x2
(整数)- 第二个点的x坐标。$y2
(整数)- 第二个点的y坐标。$color
(字符串|数组)- 线条颜色。$thickness
(整数)- 线条粗细(默认为1)。
返回一个SimpleImage对象。
polygon($vertices, $color, $thickness)
绘制多边形。
$vertices
(数组)- 多边形的顶点,以x/y数组的数组形式。例如[ ['x' => x1, 'y' => y1], ['x' => x2, 'y' => y2], ['x' => xN, 'y' => yN] ]
$color
(字符串|数组)- 多边形颜色。$thickness
(int|string) - 线条粗细(以像素为单位)或 'filled'(默认 1)。
返回一个SimpleImage对象。
rectangle($x1, $y1, $x2, $y2, $color, $thickness)
绘制矩形。
$x1
(整数)- 左上角的x坐标。$y1
(整数)- 左上角的y坐标。$x2
(整数)- 右下角的x坐标。$y2
(整数)- 右下角的y坐标。$color
(字符串|数组)- 矩形颜色。$thickness
(int|string) - 线条粗细(以像素为单位)或 'filled'(默认 1)。
返回一个SimpleImage对象。
roundedRectangle($x1, $y1, $x2, $y2, $radius, $color, $thickness)
绘制圆角矩形。
$x1
(整数)- 左上角的x坐标。$y1
(整数)- 左上角的y坐标。$x2
(整数)- 右下角的x坐标。$y2
(整数)- 右下角的y坐标。$radius
(整数)- 边框半径(像素)。$color
(字符串|数组)- 矩形颜色。$thickness
(int|string) - 线条粗细(以像素为单位)或 'filled'(默认 1)。
返回一个SimpleImage对象。
过滤器
blur($type, $passes)
应用模糊滤镜。
$type
(字符串)- 要使用的模糊算法:'selective'、'gaussian'(默认'gaussian')。$passes
(整数)- 应用滤镜的次数,增强效果(默认1)。
返回一个SimpleImage对象。
brighten($percentage)
应用亮度滤镜以增强图像。
$percentage
(整数)- 增强图像的百分比(0 - 100)。
返回一个SimpleImage对象。
colorize($color)
应用着色滤镜。
$color
(字符串|数组)- 滤镜颜色。
返回一个SimpleImage对象。
contrast($percentage)
应用对比度滤镜。
$percentage
(整数)- 调整的百分比(-100 - 100)。
返回一个SimpleImage对象。
darken($percentage)
应用亮度滤镜以暗化图像。
$percentage
(整数)- 暗化图像的百分比(0 - 100)。
返回一个SimpleImage对象。
desaturate()
应用去饱和度(灰度)滤镜。
返回一个SimpleImage对象。
duotone($lightColor, $darkColor)
对图像应用双色滤镜。
$lightColor
(字符串|数组)- 双色中最浅的颜色。$darkColor
(字符串|数组)- 双色中最深的颜色。
返回一个SimpleImage对象。
edgeDetect()
应用边缘检测滤镜。
返回一个SimpleImage对象。
emboss()
应用浮雕滤镜。
返回一个SimpleImage对象。
invert()
反转图像的颜色。
返回一个SimpleImage对象。
opacity()
更改图像的不透明度级别。
$opacity
(浮点数)- 所需的不透明度级别(0 - 1)。
返回一个SimpleImage对象。
pixelate($size)
应用像素化滤镜。
$size
(整数)- 块的大小(像素)(默认10)。
返回一个SimpleImage对象。
sepia()
通过去饱和图像并应用棕褐色调来模拟棕褐色效果。
返回一个SimpleImage对象。
sharpen($amount)
锐化图像。
$amount
(整数)- 锐化量(1 - 100,默认50)。
返回一个SimpleImage对象。
sketch()
通过应用平均去除滤镜产生草图效果。
返回一个SimpleImage对象。
颜色工具
(静态) adjustColor($color, $red, $green, $blue, $alpha)
通过独立增加/减少红/绿/蓝/alpha值来调整颜色。
$color
(字符串|数组)- 要调整的颜色。$red
(整数)- 红色调整(-255 - 255)。$green
(整数)- 绿色调整(-255 - 255)。$blue
(整数)- 蓝色调整(-255 - 255)。$alpha
(浮点数)- Alpha调整(-1 - 1)。
返回一个RGBA颜色数组。
(静态) darkenColor($color, $amount)
暗化颜色。
$color
(字符串|数组)- 要暗化的颜色。$amount
(整数)- 暗化量(0 - 255)。
返回一个RGBA颜色数组。
extractColors($count = 10, $backgroundColor = null)
像人类一样从图像中提取颜色。™ 此方法需要第三方库 \League\ColorExtractor。如果您使用 Composer,它将自动为您安装。
$count
(int) - 提取的最大颜色数量(默认 5)。$backgroundColor
(string|array) - 默认情况下,任何 Alpha 值大于零的像素将被丢弃。这是因为透明颜色不会被感知。例如,完全透明的黑色在白色背景上会被看到是白色。因此,如果您想考虑透明度,您必须指定一个默认的背景颜色。
返回一个 RGBA 颜色数组的数组。
getColorAt($x, $y)
获取单个像素的 RGBA 值。
$x
* (int) - 像素的水平位置。$y
* (int) - 像素的垂直位置。
返回一个 RGBA 颜色数组或如果 x/y 位置超出画布范围则返回 false。
(静态) lightenColor($color, $amount)
使颜色变亮。
$color
* (string|array) - 要变亮的颜色。$amount
(整数)- 暗化量(0 - 255)。
返回一个RGBA颜色数组。
(静态) normalizeColor($color)
将十六进制或数组颜色值规范化为格式良好的 RGBA 数组。
$color
* (string|array) - CSS 颜色名称、十六进制字符串或数组 [red, green, blue, alpha]。
您可以通过十六进制字符串和颜色名称传递 alpha 透明度。例如
#fff|0.50 <-- 50% 白色 red|0.25 <-- 25% 红色
返回一个数组:[red, green, blue, alpha]
异常
SimpleImage 在出错时抛出标准异常。您应该在代码周围使用 try/catch 块来正确处理它们。
<?php try { $image = new \claviska\SimpleImage('image.jpeg') // ... } catch(Exception $err) { echo $err->getMessage(); }
为了检查特定错误,将 $err->getCode()
与定义的错误常量进行比较。
<?php try { $image = new \claviska\SimpleImage('image.jpeg') // ... } catch(Exception $err) { if($err->getCode() === $image::ERR_FILE_NOT_FOUND) { echo 'File not found!'; } else { echo $err->getMessage(); } }
作为一个最佳实践,始终使用定义的常量而不是它们的整数值。这些值可能会在未来版本中更改,并且将不会被考虑为破坏性更改。
ERR_FILE_NOT_FOUND
- 由于某种原因找不到或加载指定的文件。ERR_FONT_FILE
- 无法加载指定的字体文件。ERR_FREETYPE_NOT_ENABLED
- Freetype 支持未在您的 PHP 版本中启用。ERR_GD_NOT_ENABLED
- GD 扩展未在您的 PHP 版本中启用。ERR_LIB_NOT_LOADED
- 未加载所需的库。ERR_INVALID_COLOR
- 作为参数传递了一个无效的颜色值。ERR_INVALID_DATA_URI
- 指定的数据 URI 无效。ERR_INVALID_IMAGE
- 指定的图像无效。ERR_UNSUPPORTED_FORMAT
- 指定的图像格式无效。ERR_WEBP_NOT_ENABLED
- WEBP 支持未在您的 PHP 版本中启用。ERR_WRITE
- 无法写入文件系统。
有用的知识
-
颜色参数可以是 CSS 颜色名称(例如
LightBlue
)、十六进制颜色字符串(例如#0099dd
)或 RGB(A) 数组(例如['red' => 255, 'green' => 0, 'blue' => 0, 'alpha' => 1]
)。 -
当
$thickness
> 1 时,GD 从中心起点绘制所需厚度的线条。例如,以 3 的厚度在 [10, 10, 20, 20] 处绘制的矩形实际上将在 [9, 9, 21, 21] 处绘制。这对于所有形状都适用,并且不是 SimpleImage 库中的错误。
与 SimpleImage 2.x 的区别
- 规范化的颜色参数(颜色可以是 CSS 颜色名称、十六进制或 RGB(A) 数组)。
- 规范化的 alpha(不透明度)参数:0(透明)- 1(不透明)
- 为
text
方法添加了文本阴影。 - 添加了
fromString()
方法来从字符串中加载图像。 - 添加了
toString()
方法来生成图像字符串。 - 添加了
arc
方法来绘制弧线。 - 添加了
border
方法来绘制边界。 - 添加了
dot
方法来绘制单个像素。 - 添加了
ellipse
方法来绘制椭圆和圆形。 - 添加了
line
方法来绘制线条。 - 添加了用于绘制多边形的
polygon
方法。 - 添加了用于绘制矩形的
rectangle
方法。 - 添加了用于绘制圆角矩形的
roundedRectangle
方法。 - 添加了用于修改 RGBA 颜色通道以创建相对颜色变化的
adjustColor
方法。 - 添加了用于加深颜色的
darkenColor
方法。 - 添加了用于从图像中获取最常见颜色的
extractColors
方法。 - 添加了用于获取特定像素 RGBA 值的
getColorAt
方法。 - 添加了用于加亮颜色的
lightenColor
方法。 - 添加了用于强制图像在客户端机器上下载的
toDownload
方法。 - 添加了用于创建双色图像的
duotone
滤镜。 - 添加了用于锐化图像的
sharpen
方法。 - 将命名空间从
abeautifulsite
更改为claviska
。 - 将
create
方法更改为fromNew
。 - 将
load
方法更改为fromFile
。 - 将
load_base64
方法更改为fromDataUri
。 - 将
output
方法更改为toScreen
。 - 将
output_base64
方法更改为toDataUri
。 - 将
save
方法更改为toFile
。 - 将
text
方法更改为接受选项数组而不是大量参数。 - 从
text
方法中移除了文本描边,因为它产生了脏结果,且不支持透明度。 - 移除了
smooth
方法,因为其在 PHP 手册中的参数描述不佳。 - 移除了已弃用的方法
adaptive_resize
(请使用thumbnail
代替)。 - 移除了
get_meta_data
(请使用getExif
、getHeight
、getMime
、getOrientation
和getWidth
代替)。 - 添加了 .editorconfig 文件。请在提交贡献之前确保您的编辑器支持这些设置。
- 从四个空格更改为两个空格进行缩进(对不起,PHP-FIG!)。
- 从下划线方法命名法更改为 camelCaseMethods。
- 根据功能将方法组织成组。
- 移除了 PHPDoc 注释。目前,我不希望将它们纳入库中。