Load - 84PHP开源框架

>i 本文档的最新修订日期是： > **2022-07-20** # Load ## 模块简述将浏览器上传的文件存储至服务器以及将远程的文件下载至服务器。 ## 依赖本模块依赖于PHP拓展 `cURL` 。 ## :: up()方法 ### 语法 **Load :: up ( <kbd>传参数组</kbd> )** ### 说明将浏览器上传的文件存储至服务器，并返回已上传文件的信息。此方法 `支持` 中文参数名。 ### 参数 * **`field（字段）`** `(Array)` `<必须>`：检测表单中的文件域字段（也就是HTML表单里文件域 `name` 属性的值）是否存在、是否上传了文件。此参数为一个一维数组，数组的键无需定义，值为 `字段名[,非空检查]` 的字符串。其中，`字段名` 为需要检查的字段，`非空检查` 为检查对应的字段是否有文件上传（值为 `TRUE` 或 `FALSE` ，未被定义时默认值为FALSE）。 * **`path（路径）`** `(String | Array)` `<必须>`：用以指定将上传的文件存储到何处。当传入的值的类型为 `String` 时，对所有字段生效。当传入的值的类型为 `Array` 时，此参数为一个一维数组，数组的键为字段名，值为文件存储的路径。如果一个字段在 `field` 参数中存在，而在此参数中没有，则会引发报错。路径是相对于 `应用根目录` （即Core、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)` `NULL`：用以指定单个字段内所能上传的文件数量。默认单个字段最多能够上传 `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。 * **`filename（文件名）`** `(String)` `''`：用以指定保存在本地的文件名。如果未指定本参数，那么框架将使用一个随机的文件名。 * **`path（路径）`** `(String)` `<必须>`：用以指定将下载的文件存储到何处。值为相对于 `应用根目录` （即Core、Source文件夹所在的目录，通常是站点根目录）的路径，以 `/` 开始。 * **`header（header）`** `(Array)` `[]`：用以指定需要发送的Header头，无需定义键，每一个Header中的字段作为一个元素。 * **`ssl（ssl）`** `(Bool)` `FALSE`：是否进行SSL验证。当值为 `FALSE` 时，将跳过SSL验证，但并不安全；当值为 `TRUE` 时将进行SSL验证。默认进行SSL验证。 * **`timeout（超时时间）`** `(Int)` `86400`：用以指定超时时间。值的单位为秒（s）。 ### 返回 `(String)` 类型。返回的字符串为新文件相对于 `应用根目录` （即Core、Source文件夹所在的目录，通常是站点根目录）的路径。 >w 当服务器网络不畅，或目标地址超时响应时，框架将 `报错` 。