Img - APIPHP开源框架

>i 本文档的最新修订日期是： > **2023-06-03** # Img :: 对图片进行处理。 # 依赖本模块依赖于PHP拓展 `GD2` 。 # 模块配置配置文件位于 `/config/core/Img.php` 。 * **`fontFile`** `(String)` `'/lib/img_font.ttf'` ：指定字体文件的路径。 >w 框架没有附带字体文件，需要自行添加，字体格式仅限 `TTF` 。 # 公共参数 * **`data_type（资源类型）`** `(String)` `'path'`：用以指定图片资源的类型。当值为 `path` 时，将会把参数 `image` 的值作为文件路径，进而读取文件内容。当值为 `string` 时，将会把参数 `image` 的值作为图像数据的字符串表达直接使用。当值为 `resource` 时，将会把参数 `image` 的值作为本模块 `特有的` 图像传递资源使用，通过该方式可以对一个图像进行多次修改。 * **`to（目标路径）`** `(String)` `''`：用以指定将新的图片存储到何处。当值为NULL时，将会直接输出图像，图像的MIME类型由参数 `mime` 控制。否则，值为相对于 `应用根目录`（即Core、Source文件夹所在的目录，通常是站点根目录）的路径，以 `/` 开始。当值为目标图像的路径时，`mime` 参数的值将由文件的后缀名决定，自定义的将被忽略。仅当参数 `return_resource` 值为false，或方法中不存在参数 `return_resource` 时，本参数才会生效。 * **`quality（质量）`** `(Int)` `75`：用以指定新图像的质量。值为1-100之间的整数，1为最差质量但体积最小，100为最好质量但体积最大。 >w 仅 `jpeg` 、`png` 、`webp` 类型的图片能够指定图片质量。 >w 由于 `png` 格式的质量仅有10个等级，因此将会按照给定值的 `1/10` 进行 `向下取整` 。仅当参数 `return_resource` 值为false，或方法中不存在参数 `return_resource` 时，本参数才会生效。 * **`mime（图片格式）`** `(String)` `'jpeg'`：用以指定直接输出的新图像的图片格式（MIME）。仅能在这些值中选择： `bmp` 、`gd2` 、`gd` 、`gif` 、`jpeg` 、`png` 、`vnd.wap.wbmp` 、`webp` 、`xbm` 。仅当参数 `to` 值为NULL且参数 `return_resource` 值为false时，本参数才会生效。如果方法中不存在参数 `return_resource` ，则本参数的有效性仅受参数 `to` 的控制。 * **`return_resource（返回资源）`** `(bool)` `false`：用以指定是否返回本模块 `特有的` 图像传递资源。当值为 `TRUE` 时返回，值为 `FALSE` 时不返回。 # change() ## 说明 **Img :: change ( <kbd>传参数组</kbd> )** 对图片进行大小缩放、体积压缩或添加水印。此方法 `支持` 中文参数名。 ## 参数 * **`image（源图片）`** `(String | Array)` `<必须>`：用以指定需要处理的图片的 `路径` 或图像数据的 `字符串表达` ，如何取值由参数 `data_type` 决定： 1. 如果取值方式为需要处理的图片的路径，则值为相对于 `应用根目录`（即Core、Source文件夹所在的目录，通常是站点根目录）的路径，以“/”开始。 2. 如果取值方式为图像数据的字符串表达，则值为例如用 `file_get_contents` 函数打开一个图像文件之后的得到的字符串。 3. 如果取值方式为本模块特有的图像传递资源，则值为本模块方法的返回值。 * **`data_type（资源类型）`** `(String)` `'path'`：详见本模块 `公共参数` 部分的说明。 * **`to（目标路径）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`width（宽度）`** `(Int)` `NULL`：用以指定将新的图片的宽度（单位为像素）。当值为NULL时，将会有下面两种情况： 1. 如果参数 `height` 也为NULL，此时值将受参数 `scale` 控制，即图像经过指定倍数缩放之后得到的宽度值。 2. 如果参数 `height` 不为NULL，此时值为源图片参照指定的高度等比缩放后得到的宽度值。 * **`height（高度）`** `(Int)` `NULL`：用以指定将新的图片的高度（单位为像素）。当值为NULL时，将会有下面两种情况： 1. 如果参数 `width` 也为NULL，此时值将受参数 `scale` 控制，即图像经过指定倍数缩放之后得到的高度值。 2. 如果参数 `width` 不为NULL，此时值为源图片参照指定的宽度等比缩放后得到的高度值。 * **`scale（缩放）`** `(Float)` `1.0`：用以指定新图片的尺寸相对于源图片的尺寸的倍数（即缩放的大小倍数）。值是一个大于 `0` 的整数或浮点数。例如，当值为 `0.5` 时，代表新图片的尺寸是源图片尺寸的一半；当值为 `1` 时，代表新图片的尺寸与源图片尺寸相同；当值为 `2` 时，代表新图片的尺寸是源图片尺寸的两倍。仅当参数 `width` 和参数 `height` 值均为NULL时，本参数才会生效。 * **`word（文字）`** `(String)` `NULL`：用以指定文字水印的内容。当值为 `NULL` 时，将 `不会` 为图片添加水印。 * **`word_size（文字大小）`** `(Int)` `NULL`：用以指定添加文字的尺寸。根据 `GD` 的版本，单位为像素尺寸（GD1）或点（磅）尺寸（GD2）。默认文字大小为新图片高的0.12倍。 * **`word_color（文字颜色）`** `(String)` `#333333`：用以指定添加文字的颜色。值为颜色的Hex表达式，例如 `#fa3137` 。 * **`word_margin_x（文字左边距）`** `(Int)` `0`：用以指定添加文字与新图片左侧边缘的间隔（单位为像素）。 * **`word_margin_y（文字顶边距）`** `(Int)` `0`：用以指定添加文字基线与新图片顶部边缘的间隔（单位为像素）。 * **`quality（质量）`** `(Int)` `75`：详见本模块 `公共参数` 部分的说明。 * **`mime（图片格式）`** `(String)` `jpeg`：详见本模块 `公共参数` 部分的说明。 * **`return_resource（返回资源）`** `(bool)` `false`：详见本模块 `公共参数` 部分的说明。 ## 返回无或 `(Array)` 类型。仅当参数 `return_resource` 值为true时，才会返回一个数组，该数组为本模块 `特有的` 图像传递资源。 # merge() ## 说明 **Img :: merge ( <kbd>传参数组</kbd> )** 将两个图像进行合并。此方法 `支持` 中文参数名。 ## 参数 * **`background（背景）`** `(String | Array)` `<必须>`：用以指定需要处理的背景图片的 `路径` 或图像数据的 `字符串表达` ，如何取值由参数 `data_type` 决定： 1. 如果取值方式为需要处理的背景图片的路径，则值为相对于 `应用根目录`（即Core、Source文件夹所在的目录，通常是站点根目录）的路径，以“/”开始。 2. 如果取值方式为图像数据的字符串表达，则值为例如用 `file_get_contents` 函数打开一个图像文件之后的得到的字符串。 3. 如果取值方式为本模块特有的图像传递资源，则值为本模块方法的返回值。 * **`foreground（前景）`** `(String | Array)` `<必须>`：用以指定需要处理的前景图片的 `路径` 或图像数据的 `字符串表达` ，如何取值由参数 `data_type` 决定： 1. 如果取值方式为需要处理的前景图片的路径，则值为相对于 `应用根目录`（即Core、Source文件夹所在的目录，通常是站点根目录）的路径，以“/”开始。 2. 如果取值方式为图像数据的字符串表达，则值为例如用 `file_get_contents` 函数打开一个图像文件之后的得到的字符串。 3. 如果取值方式为本模块特有的图像传递资源，则值为本模块方法的返回值。 * **`data_type（资源类型）`** `(String)` `'path'`：详见本模块 `公共参数` 部分的说明。 * **`to（目标路径）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`scale（缩放）`** `(Float)` `1.0`：用以指定前景图片尺寸的缩放倍数。值是一个大于 `0` 的整数或浮点数。例如，当值为 `0.5` 时，代表将前景图片的尺寸缩小为原来的一半；当值为 `1` 时，代表不改变前景图片的尺寸；当值为 `2` 时，代表将前景图片的尺寸放大为原来的两倍。 * **`image_x（起始X）`** `(Int)` `0`：用以指定前景图像左上角相对于背景图像的X坐标（单位为像素）。 * **`image_y（起始Y）`** `(Int)` `0`：用以指定前景图像左上角相对于背景图像的Y坐标（单位为像素）。 * **`quality（质量）`** `(Int)` `75`：详见本模块 `公共参数` 部分的说明。 * **`mime（图片格式）`** `(String)` `jpeg`：详见本模块 `公共参数` 部分的说明。 * **`return_resource（返回资源）`** `(bool)` `false`：详见本模块 `公共参数` 部分的说明。 ## 返回无或 `(Array)` 类型。仅当参数 `return_resource` 值为true时，才会返回一个数组，该数组为本模块 `特有的` 图像传递资源。 # output() ## 说明 **Img :: output ( <kbd>传参数组</kbd> )** 输出图像传递资源。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数 * **`resource（资源）`** `(Array)` `<必须>` `可简写`：本模块特有的图像传递资源，即本模块方法的返回值。 * **`to（目标路径）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`quality（质量）`** `(Int)` `75`：详见本模块 `公共参数` 部分的说明。 * **`mime（图片格式）`** `(String)` `jpeg`：详见本模块 `公共参数` 部分的说明。 ## 返回无。 # get() ## 说明 **Img :: get ( <kbd>传参数组</kbd> )** 获取图像传递资源。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数 * **`image（源图片）`** `(String | Array)` `<必须>`：用以指定需要处理的图片的 `路径` 或图像数据的 `字符串表达` ，如何取值由参数 `data_type` 决定： 1. 如果取值方式为需要处理的图片的路径，则值为相对于 `应用根目录`（即Core、Source文件夹所在的目录，通常是站点根目录）的路径，以“/”开始。 2. 如果取值方式为图像数据的字符串表达，则值为例如用 `file_get_contents` 函数打开一个图像文件之后的得到的字符串。 * **`data_type（资源类型）`** `(String)` `'path'`：详见本模块 `公共参数` 部分的说明。 ## 返回 `(Array)` 类型。返回的数组为本模块 `特有的` 图像传递资源。