Upload - APIPHP开源框架

>i 本文档的最新修订日期是： > **2024-03-09** # Upload :: 通过更便安全、捷的方式管理文件上传。通常上传文件时，会将文件的完整路径存储于数据表中。这样做的弊端有很多： * 文件路径写死在数据表中，不易修改； * 传输路径及文件名可能带来额外的安全风险； * 重复的文件路径占用数据库空间； * 文件盗链风险。因此将上传规则单独建表，并将上传的文件路径与随机生成的token建立映射，通过框架的Data模块使用文件或Redis缓存的方式缓存映射关系。上传文件时上传者将获得文件token，上传者提交数据时校验token是否有效（文件是否被上传），校验通过则将token存储于数据表内而不是存储完整的文件路径。获取文件有两种方式： * 【推荐】在代码中预先将token替换为实际存储路径，再传递给客户端； * 建立一个中转页，根据客户端传递的token，作302跳转到真实文件地址。本模块中没有实现对上传规则表的写操作，请自行根据数据表中的字段注释新建上传规则。可根据上传记录表中的reference字段来清理未被引用的文件（上传了图片但没提交）。可根据上传记录表中的status字段来进一步拓展文件上传流程（如图片压缩）。可不定期修改上传规则表中的路径和实际文件的存储路径，实现物理防盗链（狗头）。 # 依赖本模块依赖于框架模块 `Db` 、 `Data` 以及 `Load` 。本模块依赖于数据库使用。样例数据表位于 `/lib/sql/upload.sql` 。 # 模块配置配置文件位于 `/config/core/Upload.php` 。 * **`rule_table`** `(String)` `'upload_rule'` ：指定存储上传规则的数据表名。 * **`file_table`** `(String)` `'upload_file'` ：指定存储上传记录的数据表名。 * **`rule_prefix`** `(String)` `'upload_rule'` ：指定上传规则的缓存前缀。 * **`rule_prefix`** `(String)` `'upload_file'` ：指定上传记录的缓存前缀。 * **`accept`** `(Array)` `（省略）` ：此配置项为一个一维数组（Array），用以指定允许上传的文件后缀以及对应的MIME类型。`键` 为文件后缀（不含 `.` ）， `值` 为对应的MIME类型。 # 公共参数 * **`rule（规则）`** `(String)` `默认值见方法参数`：用以指定文件上传规则的代码。 * **`refresh（刷新）`** `(Bool)` `默认值见方法参数`：用以指定是否忽略缓存，直接从数据库中获取最新的上传记录或上传规则。 # getRule() ## 说明 **Upload :: getRule ( <kbd>传参数组</kbd> ) ** 获取指定的上传规则。此方法 `支持` 中文参数名。 ## 参数 * **`rule（规则）`** `(String)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`refresh（刷新）`** `(Bool)` `false`：详见本模块 `公共参数` 部分的说明。 ## 返回 `(Array|Bool)` 类型。返回值与使用Db::select()方法进行查询后所获取的结果一致，但本方法会优先获取缓存数据。如果返回值为 `false` ，则代表规则不存在。 # getAccept() ## 说明 **Upload :: getAccept ( <kbd>传参数组</kbd> ) ** 获取允许上传的文件类型。此方法 `支持` 中文参数名。 ## 参数无。 ## 返回 `(Array)` 类型。返回值与配置文件中 `accept` 参数的值一致。 # load() ## 说明 **Upload :: load ( <kbd>传参数组</kbd> ) ** 上传一个文件。此方法 `支持` 中文参数名。 ## 参数 * **`rule（规则）`** `(String)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`name（名称）`** `(String)` `<必须>`：指定表单中的文件域字段（也就是HTML表单里文件域 `name` 属性的值）。此文件域仅支持单个文件上传。 * **`data（数据）`** `(Array)` `[]`：详见 `Db` 模块 `公共参数` 部分的说明。此参数可以向上传记录表中自定义的字段（如有）添加数据。 ## 返回 `(String)` 类型。返回值为一个32位随机字符串，此字符串作为查询文件的依据。 # query() ## 说明 **Upload :: query ( <kbd>传参数组</kbd> ) ** 根据指定的token和上传规则获取文件的实际存放路径。此方法 `支持` 中文参数名。 ## 参数 * **`token（token）`** `(String)` `<必须>`：通过 `load()` 方法获取到的文件token。 * **`rule（规则）`** `(String)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`refresh（刷新）`** `(Bool)` `false`：详见本模块 `公共参数` 部分的说明。 * **`field（字段）`** `(Array)` `[]`：指定返回哪些上传记录表中自定义的字段（如有）。数组 `键` 无需定义， `值` 为字段名。 * **`reference（引用）`** `(Bool)` `false`：如果值为 `true` ，将修改上传记录表中 `reference` 字段对应的值为 `1` 。可以通过上传记录表中 `reference` 字段对应的值清理未引用（这里的未引用是指文件token从未被引用）的文件。通常传入 `true` 的时机是提交发布/修改内容时校验token是否存在时。不涉及内容改动的查询，例如展示图片时请传入 `false` 。 ## 返回 `(String)` 类型。返回值为一个32位随机字符串，此字符串作为查询文件的依据。