aingelc12ell/phpupload

这是一个非常容易使用的PHP类,用于上传文件和操作图像。从 /verot/class.upload.php 分支出来。

240813 2023-12-06 23:03 UTC

This package is auto-updated.

Last update: 2024-09-13 12:31:59 UTC


README

主页 : http://www.verot.net/php_class_upload.htm

演示 : http://www.verot.net/php_class_upload_samples.htm

捐赠: http://www.verot.net/php_class_upload_donate.htm

商业用途: http://www.verot.net/php_class_upload_license.htm

它做什么?

这个类为您管理文件上传。简而言之,它管理上传的文件,并允许您对文件进行任何操作,特别是如果它是图像,并且可以多次操作。

这是快速将文件上传集成到您网站中的理想类。如果文件是图像,您可以通过多种方式转换、调整大小和裁剪它。您还可以应用过滤器、添加边框、文字、水印等... 这就是创建图库脚本等所需的一切。支持的格式是 PNG、JPG、GIF、WEBP 和 BMP。

您还可以使用该类对本地文件进行操作,这对于使用图像处理功能特别有用。该类还支持 Flash 上传器和 XMLHttpRequest。

该类与 PHP 5.3+、PHP 7 和 PHP 8(使用版本 1.x 以支持 PHP 4)兼容,并且可以随意本地化错误消息。

通过 composer 安装

编辑您的 composer.json 文件以包含以下内容

    {
       "require": {
           "aingelc12ell/phpupload": "*"
       }
    }

或者直接安装

    composer require aingelc12ell/phpupload

演示和示例

查看 test/ 目录,您可以在浏览器中加载。您可以测试该类及其不同的实例化方式,查看一些代码示例,并运行一些测试。

如何使用它?

创建一个简单的 HTML 文件,其中包含一个表单,例如

<form enctype="multipart/form-data" method="post" action="upload.php">
  <input type="file" size="32" name="image_field" value="">
  <input type="submit" name="Submit" value="upload">
</form>

创建一个名为 upload.php 的文件(其中首先加载了该类)

$handle = new \Verot\Upload($_FILES['image_field']);
if ($handle->uploaded) {
  $handle->file_new_name_body   = 'image_resized';
  $handle->image_resize         = true;
  $handle->image_x              = 100;
  $handle->image_ratio_y        = true;
  $handle->process('/home/user/files/');
  if ($handle->processed) {
    echo 'image resized';
    $handle->clean();
  } else {
    echo 'error : ' . $handle->error;
  }
}

它是如何工作的?

您使用 $_FILES['my_field'] 数组实例化该类,其中 my_field 是您上传表单中的字段名。该类将检查原始文件是否已上传到其临时位置(或者,您也可以使用本地文件名实例化该类)。

然后,您可以设置多个处理变量来对文件执行操作。例如,您可以重命名文件,如果它是图像,可以以多种方式转换和调整大小。您还可以设置如果文件已存在,类将执行的操作。

然后调用 process() 函数来根据上述设置的参数执行操作。它将创建原始文件的副本,因此原始文件在每次处理之间保持不变。文件将被处理,并复制到指定位置。处理变量将在完成后重置。

您可以重复设置新的处理变量集,并多次调用 process()。完成时,您可以调用 clean() 来删除原始上传的文件。

如果您没有设置任何处理参数,并在实例化类后立即调用 process(),则上传的文件将简单地复制到指定位置,不做任何更改或检查。

不要忘记在表单标签 <form> 中添加 enctype="multipart/form-data",以便您的表单可以上传文件。

命名空间

现在类在 Verot/Upload 命名空间中。如果您遇到错误 致命错误:类 'Upload' 未找到,则使用类的完全限定名称,或者使用其完全限定名称实例化类

use Verot;
$handle = new Upload($_FILES['image_field']);

或者

$handle = new \Verot\Upload($_FILES['image_field']);

如何处理本地文件?

使用以下方式使用本地文件名实例化类

$handle = new \Verot\Upload('/home/user/myfile.jpg');

如何处理通过 XMLHttpRequest 上传的文件?

使用特殊关键字 php: 实例化类,如下所示

$handle = new \Verot\Upload('php:'.$_SERVER['HTTP_X_FILE_NAME']);

在参数前加上 php: 告诉类从 php://input 获取上传的数据,其余的是流文件名,通常在 $_SERVER['HTTP_X_FILE_NAME'] 中。但您可以使用任何您认为合适的名称

$handle = new \Verot\Upload('php:mycustomname.ext');

如何处理原始文件数据?

使用特殊关键字 data: 实例化类,如下所示

$handle = new \Verot\Upload('data:'.$file_contents);

如果您的数据是 base64 编码的,类提供了一个简单的 base64: 关键字,该关键字将在使用之前解码您的数据

$handle = new \Verot\Upload('base64:'.$base64_file_contents);

如何设置语言?

使用语言代码作为第二个参数实例化类

$handle = new \Verot\Upload($_FILES['image_field'], 'fr_FR');
$handle = new \Verot\Upload('/home/user/myfile.jpg', 'fr_FR');

如何将生成的文件或图片直接输出到浏览器?

只需不带参数(或以 null 作为第一个参数)调用 process()

$handle = new \Verot\Upload($_FILES['image_field']);
header('Content-type: ' . $handle->file_src_mime);
echo $handle->process();
die();

或者,如果您想强制下载文件

$handle = new \Verot\Upload($_FILES['image_field']);
header('Content-type: ' . $handle->file_src_mime);
header("Content-Disposition: attachment; filename=".rawurlencode($handle->file_src_name).";");
echo $handle->process();
die();

关于安全性的警告

默认情况下,该类依赖于 MIME 类型检测来评估文件是否可以上传。根据服务器配置,使用了多种 MIME 类型检测方法。该类依赖于危险文件扩展名的黑名单来防止上传(或将危险的脚本重命名为文本文件),以及接受 MIME 类型的白名单。

但这个类不是为了进行深入的检查和启发式分析来尝试检测恶意构造的文件。例如,攻击者可以构造一个具有正确 MIME 类型的文件,但携带恶意负载,例如一个包含一些导致 XSS 漏洞的代码的有效 GIF 文件。如果这个 GIF 文件有 .html 扩展名,它可能被上传(取决于类的设置)并显示 XSS 漏洞。

然而,您可以通过使用 allowedforbidden 来限制可以上传的文件类型,根据它们的 MIME 类型或扩展名进行白名单和黑名单操作。最安全的选择是仅允许通过白名单扩展名,并确保您的服务器始终根据文件扩展名提供基于内容的类型。

例如,如果您只想允许一种类型的文件,您可以通过仅允许其文件扩展名来进行白名单操作。在下面的示例中,只允许通过 .html 文件,并且不会被转换为文本文件

$handle->allowed   = array('html');
$handle->forbidden = array();
$handle->no_script = false;

最后,确保上传正确文件的责任在于您。但更重要的是,您有责任正确提供上传的文件,例如通过强制服务器根据文件扩展名始终提供内容类型。

故障排除

如果类没有按照您期望的方式工作,您可以显示日志,以便详细了解类做了什么。要获取日志,只需在代码末尾添加此行

echo $handle->log;

您的问题可能已经在常见问题解答中讨论过: http://www.verot.net/php_class_upload_faq.htm

如果没有,您可以在论坛中搜索,并在那里提问: http://www.verot.net/php_class_upload_forum.htm。请勿使用 Github issues 来寻求帮助。

处理参数

注意:本节中的所有参数在每个处理之后都会重置。

文件处理

  • file_new_name_body 替换名称体(默认:null)
$handle->file_new_name_body = 'new name';
  • file_name_body_add 追加到文件名主体(默认:null)
$handle->file_name_body_add = '_uploaded';
  • file_name_body_pre 预加到文件名主体(默认:null)
$handle->file_name_body_pre = 'thumb_';
  • file_new_name_ext 替换文件扩展名(默认:null)
$handle->file_new_name_ext = 'txt';
  • file_safe_name 格式化文件名(空格更改为下划线等...)(默认:true)
$handle->file_safe_name = true;
  • file_force_extension 如果没有扩展名则强制添加扩展名(默认:true)
$handle->file_force_extension = true;
  • file_overwrite 设置文件已存在时的行为(默认:false)
$handle->file_overwrite = true;
  • file_auto_rename 如果文件已存在则自动重命名文件(默认:true)
$handle->file_auto_rename = true;
  • dir_auto_create 如果缺失则自动创建目标目录(默认:true)
$handle->dir_auto_create = true;
  • dir_auto_chmod 如果目标目录不可写则自动尝试更改目录权限(默认:true)
$handle->dir_auto_chmod = true;
  • dir_chmod 创建目录或目录不可写时使用的chmod(默认:0777)
$handle->dir_chmod = 0777;
  • file_max_size 设置最大上传大小(默认:从php.ini中的upload_max_filesize获取)
$handle->file_max_size = '1024'; // 1KB
  • mime_check 设置类是否检查MIME与allowed列表的匹配(默认:true)
$handle->mime_check = true;
  • no_script 设置类是否将危险脚本转换为文本文件(默认:true)
$handle->no_script = false;
  • allowed 允许的MIME类型或文件扩展名数组(或一个字符串)。接受通配符,例如 image/*(默认:检查init()
$handle->allowed = array('application/pdf','application/msword', 'image/*');
  • forbidden 禁止的MIME类型或文件扩展名数组(或一个字符串)。接受通配符,例如 image/*(默认:检查init()
$handle->forbidden = array('application/*');

图片处理

  • image_convert 如果设置,图片将被转换(可能的值:''|'png'|'webp'|'jpeg'|'gif'|'bmp';默认:'')
$handle->image_convert = 'jpg';
  • image_background_color 如果设置,将强制用颜色填充透明区域,以十六进制表示(默认:null)
$handle->image_background_color = '#FF00FF';
  • image_default_color 用于非alpha透明输出格式(如JPEG或BMP)的回退颜色背景,以十六进制表示(默认:#FFFFFF)
$handle->image_default_color = '#FF00FF';
  • png_compression 设置PNG图片的压缩级别,介于1(快速但文件大)和9(慢但文件小)之间(默认:null(Zlib默认))
$handle->png_compression = 9;
  • webp_quality 设置WEBP图片的压缩质量(默认:85)
$handle->webp_quality = 50;
  • jpeg_quality 设置JPEG图片的压缩质量(默认:85)
$handle->jpeg_quality = 50;
  • jpeg_size 如果设置为字节数,将约化jpeg_quality,以便输出图片适合该大小(默认:null)
$handle->jpeg_size = 3072;
  • image_interlace 如果设置为true,图片将被交错保存(如果是JPEG,将保存为渐进式PEG)(默认:false)
$handle->image_interlace = true;

图片检查

以下八个设置可以在文件是图片时使上传无效(注意,open_basedir限制阻止使用这些设置)

  • image_max_width 如果设置为像素尺寸,则上传无效,如果图片宽度更大(默认:null)
$handle->image_max_width = 200;
  • image_max_height 如果设置为像素尺寸,则上传无效,如果图片高度更大(默认:null)
$handle->image_max_height = 100;
  • image_max_pixels 如果设置为像素数,则上传无效,如果图片像素数更大(默认:null)
$handle->image_max_pixels = 50000;
  • image_max_ratio 如果设置为宽高比(宽度/高度),则上传无效,如果图片宽高比更大(默认:null)
$handle->image_max_ratio = 1.5;
  • image_min_width 如果设置为像素尺寸,则上传无效,如果图片宽度更小(默认:null)
$handle->image_min_width = 100;
  • image_min_height 如果设置为像素尺寸,则上传无效,如果图片高度更小(默认:null)
$handle->image_min_height = 500;
  • image_min_pixels 如果设置为像素数,则上传无效,如果图片像素数更小(默认:null)
$handle->image_min_pixels = 20000;
  • image_min_ratio 如果设置为宽高比(宽度/高度),则上传无效,如果图片宽高比更小(默认:null)
$handle->image_min_ratio = 0.5;

图片缩放

  • image_resize 确定图片是否将被缩放(默认:false)
$handle->image_resize = true;

以下变量仅在 image_resize == true 时使用

  • image_x 目标图像宽度(默认:150)
$handle->image_x = 100;
  • image_y 目标图像高度(默认:150)
$handle->image_y = 200;

使用以下任何一个

  • image_ratio 如果为 true,则保持原始大小比例调整图像大小,使用 image_x image_y 作为最大尺寸(默认:false)
$handle->image_ratio = true;
  • image_ratio_crop 如果为 true,则保持原始大小比例调整图像大小,使用 image_ximage_y 作为最大尺寸,并裁剪超出部分以填充空间。设置也可以是字符串,包含一个或多个来自 'TBLR' 的字符,指示裁剪时保留图像的哪一侧(默认:false)
$handle->image_ratio_crop = true;
  • image_ratio_fill 如果为 true,则保持原始大小比例调整图像大小,使用 image_ximage_y 作为最大尺寸,适应空间并着色剩余空间。设置也可以是字符串,包含一个或多个来自 'TBLR' 的字符,指示图像将在空间的哪一侧(默认:false)
$handle->image_ratio_fill = true;
  • image_ratio_x 如果为 true,则调整图像大小,从 image_y 计算出 image_x 并保持原始大小比例(默认:false)
$handle->image_ratio_x = true;
  • image_ratio_y 如果为 true,则调整图像大小,从 image_x 计算出 image_y 并保持原始大小比例(默认:false)
$handle->image_ratio_y = true;
  • image_ratio_pixels 如果设置为长整数,则调整图像大小,将 image_yimage_x 调整到匹配像素数(默认:false)
$handle->image_ratio_pixels = 25000;

最终防止放大或缩小图像

  • image_no_enlarging 如果调整大小后的图像大于原始图像,则取消调整大小以防止放大(默认:false)
$handle->image_no_enlarging = true;
  • image_no_shrinking 如果调整大小后的图像小于原始图像,则取消调整大小以防止缩小(默认:false)
$handle->image_no_shrinking = true;

图像效果

以下图像操作需要 GD2+

  • image_brightness 如果设置,则校正亮度。值在 -127 和 127 之间(默认:null)
$handle->image_brightness = 40;
  • image_contrast 如果设置,则校正对比度。值在 -127 和 127 之间(默认:null)
$handle->image_contrast = 50;
  • image_opacity 如果设置,则改变图像不透明度。值在 0 和 100 之间(默认:null)
$handle->image_opacity = 50;
  • image_tint_color 如果设置,则用颜色着色图像,值作为十六进制 #FFFFFF(默认:null)
$handle->image_tint_color = '#FF0000';
  • image_overlay_color 如果设置,则添加彩色叠加,值作为十六进制 #FFFFFF(默认:null)
$handle->image_overlay_color = '#FF0000';
  • image_overlay_opacityimage_overlay_color 设置时使用,确定不透明度(默认:50)
$handle->image_overlay_opacity = 20;
  • image_negative 反转图像中的颜色(默认:false)
$handle->image_negative = true;
  • image_greyscale 将图像转换为灰度(默认:false)
$handle->image_greyscale = true;
  • image_threshold 应用阈值过滤器。值在 -127 和 127 之间(默认:null)
$handle->image_threshold = 20;
  • image_pixelate 像素化图像,值是块大小(默认:null)
$handle->image_pixelate = 10;
  • image_unsharp 应用不锐化蒙版,支持 alpha 透明度(默认:false)
$handle->image_unsharp = true;
  • image_unsharp_amount 不锐化蒙版数量,通常是 50 - 200(默认:80)
$handle->image_unsharp_amount = 120;
  • image_unsharp_radius 不锐化蒙版半径,通常是 0.5 - 1(默认:0.5)
$handle->image_unsharp_radius = 1;
  • image_unsharp_threshold 不锐化蒙版阈值,通常是 0 - 5(默认:1)
$handle->image_unsharp_threshold = 0;

图像文本

  • image_text 在图像上创建文本标签,值是一个字符串,包含可能的替换令牌(默认:null)
$handle->image_text = 'test';
  • image_text_direction 文本标签方向,'h' 水平或 'v' 垂直(默认:'h')
$handle->image_text_direction = 'v';
  • image_text_color 文本标签的文本颜色,十六进制(默认:#FFFFFF)
$handle->image_text_color = '#FF0000';
  • image_text_opacity 文本标签的文本不透明度,介于 0 和 100 之间的整数(默认:100)
$handle->image_text_opacity = 50;
  • image_text_background 文本标签背景颜色,十六进制(默认:null)
$handle->image_text_background = '#FFFFFF';
  • image_text_background_opacity 文本标签背景不透明度,介于 0 和 100 之间的整数(默认:100)
$handle->image_text_background_opacity = 50;
  • image_text_font 文本标签的内建字体,从 1 到 5。1 是最小的(默认:5)。值也可以是一个字符串,表示 GDF 或 TTF 字体的路径(TrueType)。
$handle->image_text_font = 4; // or './font.gdf' or './font.ttf'
  • image_text_size TrueType 字体的字体大小,以像素(GD1)或点(GD1)为单位(默认:16)(仅限 TrueType 字体)
$handle->image_text_size = 24;
  • image_text_angle TrueType 字体的文本角度,以度为单位,0 度为从左到右阅读的文本(默认:null)(仅限 TrueType 字体)
$handle->image_text_angle = 45;
  • image_text_x 绝对文本标签位置,从左侧边界的像素。可以是负数(默认:null)
$handle->image_text_x = 5;
  • image_text_y 绝对文本标签位置,从顶部边界的像素。可以是负数(默认:null)
$handle->image_text_y = 5;
  • image_text_position 图像中的文本标签位置,可以是 'TBLR' 中的一个或两个的组合:顶部、底部、左侧、右侧(默认:null)
$handle->image_text_position = 'LR';
  • image_text_padding 文本标签填充,以像素为单位。可以被 image_text_padding_ximage_text_padding_y 覆盖(默认:0)
$handle->image_text_padding = 5;
  • image_text_padding_x 文本标签水平填充(默认:null)
$handle->image_text_padding_x = 2;
  • image_text_padding_y 文本标签垂直填充(默认:null)
$handle->image_text_padding_y = 10;
  • image_text_alignment 当文本有多个行时,文本对齐方式,可以是 'L'、'C' 或 'R'(默认:'C')(仅限 GD 字体)
$handle->image_text_alignment = 'R';
  • image_text_line_spacing 当文本有多个行时,行间距,以像素为单位(默认:0)(仅限 GD 字体)
$handle->image_text_line_spacing = 3;

图像变换

  • image_auto_rotate 根据 EXIF 数据自动旋转图像(仅限 JPEG)(默认:true,即使没有图像操作也会应用)
$handle->image_auto_rotate = false;
  • image_flip 翻转图像,'h' 为水平翻转,'v' 为垂直翻转(默认:null)
$handle->image_flip = 'h';
  • image_rotate 旋转图像。可能的值为 90、180 和 270(默认:null)
$handle->image_rotate = 90;
  • image_crop 裁剪图像。接受 4、2 或 1 个值作为 'T R B L' 或 'TB LR' 或 'TBLR'。尺寸可以是 20、20px 或 20%(默认:null)
$handle->image_crop = array(50,40,30,20); OR '-20 20%'...
  • image_precrop 在最终调整大小之前裁剪图像。接受 4、2 或 1 个值作为 'T R B L' 或 'TB LR' 或 'TBLR'。尺寸可以是 20、20px 或 20%(默认:null)
$handle->image_precrop = array(50,40,30,20); OR '-20 20%'...

图像边框

  • image_bevel 向图像添加斜边框。值是像素厚度(默认:null)
$handle->image_bevel = 20;
  • image_bevel_color1 顶部和左侧斜边框颜色,十六进制表示(默认:#FFFFFF)
$handle->image_bevel_color1 = '#FFFFFF';
  • image_bevel_color2 底部和右侧斜边框颜色,十六进制表示(默认:#000000)
$handle->image_bevel_color2 = '#000000';
  • image_border 向图像添加单色边框。接受 4、2 或 1 个值作为 'T R B L' 或 'TB LR' 或 'TBLR'。尺寸可以是 20、20px 或 20%(默认:null)
$handle->image_border = '3px'; OR '-20 20%' OR array(3,2)...
  • image_border_color 边框颜色,十六进制表示(默认:#FFFFFF)
$handle->image_border_color = '#FFFFFF';
  • image_border_opacity 边框不透明度,介于 0 和 100 之间的整数(默认:100)
$handle->image_border_opacity = 50;
  • image_border_transparent 向图像添加渐变至透明的边框。接受 4、2 或 1 个值作为 'T R B L' 或 'TB LR' 或 'TBLR'。尺寸可以是 20、20px 或 20%(默认:null)
$handle->image_border_transparent = '3px'; OR '-20 20%' OR array(3,2)...
  • image_frame 边框类型:1=平面 2=交叉(默认:null)
$handle->image_frame = 2;
  • image_frame_colors十六进制颜色列表,为数组或以空格分隔的字符串(默认:'#FFFFFF #999999 #666666 #000000')
$handle->image_frame_colors = array('#999999',  '#FF0000', '#666666', '#333333', '#000000');
  • image_frame_opacity 边框不透明度,介于 0 和 100 之间的整数(默认:100)
$handle->image_frame_opacity = 50;

图像水印

  • image_watermark 在图像上添加水印,值是本地文件名。接受的文件格式是 GIF、JPG、BMP、WEBP、PNG 和 PNG alpha(默认:null)
$handle->image_watermark = 'watermark.png';
  • image_watermark_x 水印的绝对位置,从左侧边界的像素。可以是负数(默认:null)
$handle->image_watermark_x = 5;
  • image_watermark_y 水印的绝对位置,从顶部边界的像素。可以是负数(默认:null)
$handle->image_watermark_y = 5;
  • image_watermark_position 水印在图像中的位置,可以是 'TBLR' 中的一个或两个的组合:顶部、底部、左侧、右侧(默认:null)
$handle->image_watermark_position = 'LR';
  • image_watermark_no_zoom_in 防止水印在小于图像时被放大(默认:true)
$handle->image_watermark_no_zoom_in = false;
  • image_watermark_no_zoom_out 防止水印在大于图像时被缩小(默认:false)
$handle->image_watermark_no_zoom_out = true;

图像反射

  • image_reflection_height 如果设置,则会添加反射。格式为像素或百分比,例如40、'40'、'40px'或'40%'(默认:null)
$handle->image_reflection_height = '25%';
  • image_reflection_space 源图像和反射之间的像素空间,可以是负值(默认:null)
$handle->image_reflection_space = 3;
  • image_reflection_color 反射背景颜色,十六进制格式。现在已弃用,推荐使用image_default_color(默认:#FFFFFF)
$handle->image_default_color = '#000000';
  • image_reflection_opacity 反射开始的透明度级别,介于0到100之间的整数(默认:60)
$handle->image_reflection_opacity = 60;

在调用process()之前可以读取的值

  • file_src_name 源文件名
  • file_src_name_body 源文件名主体
  • file_src_name_ext 源文件扩展名
  • file_src_pathname 源文件完整路径和名称
  • file_src_mime 源文件MIME类型
  • file_src_size 源文件大小,字节数
  • file_src_error 上传错误代码
  • file_is_image 布尔标志,如果文件是支持的图像类型则为true

如果文件是支持的图像类型(并且open_basedir限制允许)

  • image_src_x 源文件宽度,像素
  • image_src_y 源文件高度,像素
  • image_src_pixels 源文件像素数量
  • image_src_type 源文件类型(png、webp、jpg、gif或bmp)
  • image_src_bits 源文件颜色深度

在调用process()之后可以读取的值

  • file_dst_path 目标文件路径
  • file_dst_name_body 目标文件名主体
  • file_dst_name_ext 目标文件扩展名
  • file_dst_name 目标文件名
  • file_dst_pathname 目标文件完整路径和名称

如果文件是支持的图像类型

  • image_dst_type 目标文件类型(png、webp、jpg、gif或bmp)
  • image_dst_x 目标文件宽度
  • image_dst_y 目标文件高度

要求

大多数图像操作需要GD。GD2被强烈推荐

1.x版本支持PHP 4、5和7,但没有命名空间。如果需要支持PHP <5.3,请使用它

2.x版本支持PHP 5.3+、PHP 7和PHP 8。