turbo/image

基于claviska/simpleimage,支持图片圆角、载入gd resource

v0.4 2020-05-02 15:12 UTC

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

要求

功能

  • 支持读取、写入和转换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

神奇顺序

  1. 加载图像
  2. 操作图像
  3. 保存/输出图像

API技巧

  • 星号(*)表示必需参数。
  • 返回SimpleImage对象的方法定义为链式可用的。
  • 您可以通过构造函数传递文件或数据URI来避免调用fromFilefromDataUri
  • 可以使用$image::methodName()\claviska\SimpleImage::methodName()调用静态方法。
  • 颜色可以是CSS颜色(例如 white)、十六进制字符串(例如 #ffffff)或RGBA数组。
  • 当您传递CSS颜色或十六进制字符串时,可以将透明度传递给normalizeColorwhite|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(请使用 getExifgetHeightgetMimegetOrientationgetWidth 代替)。
  • 添加了 .editorconfig 文件。请在提交贡献之前确保您的编辑器支持这些设置。
  • 从四个空格更改为两个空格进行缩进(对不起,PHP-FIG!)。
  • 从下划线方法命名法更改为 camelCaseMethods。
  • 根据功能将方法组织成组。
  • 移除了 PHPDoc 注释。目前,我不希望将它们纳入库中。