Load
<br/>
>i 本文档的最新修订日期是:
> **2022-07-20**
# Load
## 模块简述
将浏览器上传的文件存储至服务器以及将远程的文件下载至服务器。
## 依赖
本模块依赖于PHP拓展 <font color="#c7254e">`cURL`</font> 。
## :: up()方法
### 语法
**<font color="#0099ff"><font color="#ff6600">Load</font> :: <font color="#ff6600">up</font> ( <kbd>传参数组</kbd> )</font>**
### 说明
将浏览器上传的文件存储至服务器,并返回已上传文件的信息。
此方法 <font color="#c7254e">`支持`</font> 中文参数名。
### 参数
* **<font color="#ff6600">`field(字段)`</font>** <font color="#0099ff">`(Array)`</font> <font color="#BBBBBB">`<必须>`</font>:
检测表单中的文件域字段(也就是HTML表单里文件域 <font color="#c7254e">`name`</font> 属性的值)是否存在、是否上传了文件。
此参数为一个一维数组,数组的键无需定义,值为 <font color="#c7254e">`字段名[,非空检查]`</font> 的字符串。
其中,<font color="#c7254e">`字段名`</font> 为需要检查的字段,<font color="#c7254e">`非空检查`</font> 为检查对应的字段是否有文件上传(值为 <font color="#c7254e">`TRUE`</font> 或 <font color="#c7254e">`FALSE`</font> ,未被定义时默认值为FALSE)。
* **<font color="#ff6600">`path(路径)`</font>** <font color="#0099ff">`(String | Array)`</font> <font color="#BBBBBB">`<必须>`</font>:
用以指定将上传的文件存储到何处。
当传入的值的类型为 <font color="#c7254e">`String`</font> 时,对所有字段生效。
当传入的值的类型为 <font color="#c7254e">`Array`</font> 时,此参数为一个一维数组,数组的键为字段名,值为文件存储的路径。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会引发报错。
路径是相对于 <font color="#c7254e">`应用根目录`</font> (即Core、Source文件夹所在的目录,通常是站点根目录)的路径,以 <font color="#c7254e">`/`</font> 开始。
* **<font color="#ff6600">`type(类型)`</font>** <font color="#0099ff">`(String | Array)`</font> <font color="#BBBBBB">`<必须>`</font>:
用以指定所允许的文件上传类型。
所有允许上传的文件 <font color="#c7254e">`后缀名`</font> 用 <font color="#c7254e">`,`</font> 分隔,组成那个一个字符串。
当传入的值的类型为 <font color="#c7254e">`String`</font> 时,对所有字段生效。
当传入的值的类型为 <font color="#c7254e">`Array`</font> 时,此参数为一个一维数组,数组的键为字段名,值为允许的文件类型。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会引发报错。
* **<font color="#ff6600">`save_name(保存名称)`</font>** <font color="#0099ff">`(Array)`</font> <font color="#BBBBBB">`NULL`</font>:
用以指定新文件的文件名 <font color="#c7254e">`前缀`</font> 。
默认采用 <font color="#c7254e">`32位随机MD5值`</font> 作为文件名的前缀。
此参数为一个一维数组,数组的键为字段名,值为文件的前缀。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会使用默认值。
>w 如果一个字段中上传了多个文件,则此参数不会生效。
* **<font color="#ff6600">`size(大小)`</font>** <font color="#0099ff">`(Int | Array)`</font> <font color="#BBBBBB">`10240`</font>:
用以指定所上传文件的最大大小。
单位是 <font color="#c7254e">`KB`</font> ,默认值为10240(即10MB)。
当传入的值的类型为 <font color="#c7254e">`Int`</font> 时,对所有字段生效。
当传入的值的类型为 <font color="#c7254e">`Array`</font> 时,此参数为一个一维数组,数组的键为字段名,值为允许的文件类型。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会使用默认值。
* **<font color="#ff6600">`number(数量)`</font>** <font color="#0099ff">`(Int | Array)`</font> <font color="#BBBBBB">`NULL`</font>:
用以指定单个字段内所能上传的文件数量。
默认单个字段最多能够上传 <font color="#c7254e">`1`</font> 个文件。
当传入的值的类型为 <font color="#c7254e">`Int`</font> 时,对所有字段生效。
当传入的值的类型为 <font color="#c7254e">`Array`</font> 时,此参数为一个一维数组,数组的键为字段名,值为允许上传的文件数量。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会使用默认值。
* **<font color="#ff6600">`ignore_error(忽略错误)`</font>** <font color="#0099ff">`(Bool)`</font> <font color="#BBBBBB">`FALSE`</font>:
用以指定是否忽略上传过程中遇到的错误。
当值为 <font color="#c7254e">`FALSE`</font> 时,如果上传过程中遇到错误,将会中断程序运行,并进行报错。
当值为 <font color="#c7254e">`TRUE`</font> 时,如果上传过程中遇到错误,不会中断程序运行,但返回的文件名将变为 <font color="#c7254e">`NULL`</font> 。
### 返回
<font color="#0099ff">`(Array)`</font> 类型。
返回的值为 <font color="#c7254e">`Array`</font> 类型,其中键为 <font color="#c7254e">`field`</font> 参数中定义的字段名,值为已上传文件的文件名的字符串。当一个字段中上传了多个文件时,值将变为一个由所有已上传文件的文件名组成的数组。
>d 务必注意在服务器中设置 <font color="#c7254e">`资源的响应方式`</font> (例如访问一个PDF文档时,服务器是直接展示还是提供下载),这关系到服务器的安全。
>d 如果要将保存时的文件名设定为上传文件原本的文件名,务必对文件名进行安全过滤。
>w 务必在前端页面中,即表单页通过HTML代码和JS来限制文件的 <font color="#c7254e">`上传类型`</font> 和 <font color="#c7254e">`大小`</font> ,这样用户体验更加友好,也可以拦截大部分使用者 <font color="#c7254e">`无意的非法操作`</font> 。
## :: down()方法
### 语法
**<font color="#0099ff"><font color="#ff6600">Load</font> :: <font color="#ff6600">down</font> ( <kbd>传参数组</kbd> )</font>**
### 说明
从远程下载文件至服务器。
此方法 <font color="#c7254e">`支持`</font> 中文参数名。
### 参数
* **<font color="#ff6600">`url(地址)`</font>** <font color="#0099ff">`(String)`</font> <font color="#BBBBBB">`<必须>`</font>:
用以指定需要下载的URL。
* **<font color="#ff6600">`filename(文件名)`</font>** <font color="#0099ff">`(String)`</font> <font color="#BBBBBB">`''`</font>:
用以指定保存在本地的文件名。
如果未指定本参数,那么框架将使用一个随机的文件名。
* **<font color="#ff6600">`path(路径)`</font>** <font color="#0099ff">`(String)`</font> <font color="#BBBBBB">`<必须>`</font>:
用以指定将下载的文件存储到何处。
值为相对于 <font color="#c7254e">`应用根目录`</font> (即Core、Source文件夹所在的目录,通常是站点根目录)的路径,以 <font color="#c7254e">`/`</font> 开始。
* **<font color="#ff6600">`header(header)`</font>** <font color="#0099ff">`(Array)`</font> <font color="#BBBBBB">`[]`</font>:
用以指定需要发送的Header头,无需定义键,每一个Header中的字段作为一个元素。
* **<font color="#ff6600">`ssl(ssl)`</font>** <font color="#0099ff">`(Bool)`</font> <font color="#BBBBBB">`FALSE`</font>:
是否进行SSL验证。
当值为 <font color="#c7254e">`FALSE`</font> 时,将跳过SSL验证,但并不安全;当值为 <font color="#c7254e">`TRUE`</font> 时将进行SSL验证。默认进行SSL验证。
* **<font color="#ff6600">`timeout(超时时间)`</font>** <font color="#0099ff">`(Int)`</font> <font color="#BBBBBB">`86400`</font>:
用以指定超时时间。
值的单位为秒(s)。
### 返回
<font color="#0099ff">`(String)`</font> 类型。
返回的字符串为新文件相对于 <font color="#c7254e">`应用根目录`</font> (即Core、Source文件夹所在的目录,通常是站点根目录)的路径。
>w 当服务器网络不畅,或目标地址超时响应时,框架将 <font color="#c7254e">`报错`</font> 。