Load - APIPHP开源框架

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