Download the PHP package tinywan/storage without Composer
On this page you can find all versions of the php package tinywan/storage. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package storage
📑 目录
- 特性
- 能力矩阵
- 安装
- 快速开始
- 上传规则
- 上传验证
- 云端 SDK
- 上传 Base64 图片
- 上传服务端文件
- 大文件分片上传（本地）
- 工作流程
- 相关配置
- ① 上传分片 uploadChunk
- ② 断点续传查询 chunkProgress
- ③ 合并分片 mergeChunk
- 大文件分片上传（云端）
- 实现方式
- 代码质量
✨ 特性
- 🗃️ 多存储统一 API —— 本地、阿里云 OSS、腾讯云 COS、七牛云、AWS S3 一键切换
- 📤 多文件上传 —— 一次请求上传多个文件，返回结构化结果
- 🖼️ Base64 上传 —— 前端截图 / Canvas 数据流直传云端
- 🗂️ 服务端文件上传 —— 服务端导出文件直接转存云端
- 🧩 大文件分片上传 —— 前端切片、逐片校验、断点续传、自动合并（本地与全部云端存储）
- 🔒 上传验证 —— 大小、数量、后缀黑白名单全支持
能力矩阵
| 云端 | 多文件上传 | Base64 图片上传 | 服务器文件上传 | 大文件分片上传 |
|---|---|---|---|---|
| 🍏 私有云（本地） | ✅ | — | ✅ | ✅ |
| 🍓 阿里云 | ✅ | ✅ | ✅ | ✅ |
| 🍋 腾讯云 | ✅ | ✅ | ✅ | ✅ |
| 🍇 七牛云 | ✅ | ✅ | ✅ | ✅ |
| 🌰 亚马逊（S3） | ✅ | ✅ | ✅ | ✅ |
🚀 安装
[!NOTE] 要求
PHP >= 7.2、workerman/webman-framework ^1.5.4 || ^2.0。 插件安装后自动发布配置到config/plugin/tinywan/storage/app.php。
⚡ 快速开始
[!NOTE] 无需手动初始化，默认使用配置
storage.default指定的上传适配器。
上传成功信息
[!WARNING] 上传失败时抛出
StorageException异常。
成功响应字段
| 字段 | 描述 | 示例值 |
|---|---|---|
key |
上传文件 key | webman |
origin_name |
原始文件名 | 常用编程软件和工具.xlsx |
save_name |
保存文件名 | 03414c9bdaf7a38148742c87b96b8167.xlsx |
save_path |
文件保存路径 | /var/www/webman-admin/runtime/storage/03414c9bdaf7a38148742c87b96b8167.xlsx |
url |
url 访问路径 | /storage/03414c9bdaf7a38148742c87b96b8167.xlsx |
unique_id |
文件散列值 | 03414c9bdaf7a38148742c87b96b8167 |
size |
文件大小（字节） | 15050 |
mime_type |
文件类型 | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
extension |
文件扩展名 | xlsx |
📁 上传规则
默认上传到本地服务器，在 runtime/storage 目录下生成以当前日期为子目录、以文件流散列值（algo 配置，默认 sha1）为文件名的文件：
如果希望上传的文件可以直接访问或下载，可以将上传根目录配置到 public 目录。在 config/plugin/tinywan/storage/app.php 中配置：
浏览器访问：http://127.0.0.1:8787/storage/fd2d472da56c71a6da0a5251f5e1b586.png
🛡️ 上传验证
支持对上传文件的大小、数量、类型和后缀进行验证：
| 字段 | 描述 | 示例值 |
|---|---|---|
single_limit |
单个文件的大小限制，默认 200M | 1024 * 1024 * 200 |
total_limit |
所有文件的大小限制，默认 200M | 1024 * 1024 * 200 |
nums |
文件数量限制，默认 10 | 10 |
include |
被允许的文件类型列表（白名单） | ['xlsx', 'pdf'] |
exclude |
不被允许的文件类型列表（黑名单） | ['png', 'jpg'] |
☁️ 云端 SDK
按需安装对应云存储 SDK 后，仅需切换 Storage::disk() 参数即可：
| 云存储 | 安装命令 | 磁盘常量 |
|---|---|---|
| 🍓 阿里云 OSS | composer require aliyuncs/oss-sdk-php |
Storage::MODE_OSS |
| 🍋 腾讯云 COS | composer require qcloud/cos-sdk-v5 |
Storage::MODE_COS |
| 🍇 七牛云 | composer require qiniu/php-sdk |
Storage::MODE_QINIU |
| 🌰 亚马逊 S3 | composer require league/flysystem-aws-s3-v3 |
Storage::MODE_S3 |
🖼️ 上传 Base64 图片
使用场景： 前端直接截图（头像、Canvas 等）生成 Base64 数据流的图片，直接上传到云端。
请求参数
请求示例（阿里云）
响应参数
🗂️ 上传服务端文件
使用场景： 服务端导出的文件需要上传到云端存储，或者临时下载文件存储。
请求示例（阿里云）
响应参数
🧩 大文件分片上传（本地）
使用场景： 大文件（超出
upload_max_filesize或网络不稳定）由前端切片后逐片上传，服务端校验并合并。目前仅本地适配器支持，云端适配器（OSS/COS/七牛/S3）后续版本支持。🧪 端到端测试示例见
example/：示例控制器、路由和 curl 一键测试脚本。
工作流程
相关配置
① 上传分片 uploadChunk
响应参数：
[!NOTE] 同一
chunk_index重复上传会覆盖旧分片（断点续传语义）；md5 校验失败会抛出StorageException且不落盘。
② 断点续传查询 chunkProgress
响应参数（前端根据 missing 补传缺失分片）：
③ 合并分片 mergeChunk
响应参数与普通上传单文件结构一致（origin_name/save_name/save_path/url/unique_id/size/mime_type/extension），最终文件名为 文件散列值.扩展名，合并成功后自动清理分片临时目录。
[!WARNING]
- 分片上传必须使用
Storage::disk(MODE_LOCAL, false)方式调用（跳过 HTTP 文件上传校验）- 合并过程有独占锁，重复触发会提示"文件正在合并中"
- 中断未合并的分片临时目录（
chunk_path下）暂不自动清理，请由业务侧定期清理
☁️ 大文件分片上传（云端）
阿里云 OSS、腾讯云 COS、AWS S3、七牛云同样支持 uploadChunk / chunkProgress / mergeChunk，调用方式与本地完全一致，仅 disk 不同：
🧪 端到端测试示例见
example/：同一套路由通过disk参数切换本地与云端，如DISK=oss ./chunk-upload-test.sh video.mp4
实现方式
| 云端 | 实现 |
|---|---|
| 阿里云 OSS / 腾讯云 COS / AWS S3 | 厂商原生 Multipart Upload：首片自动 initiate，逐片 uploadPart，合并时 complete 后 copy 为最终对象并删除临时对象 |
| 七牛云 | 分片本地暂存，合并后整体 putFile 上传（SDK 内部自动断点续传） |
- 会话状态：OSS / COS / S3 的
uploadId与各分片 ETag 持久化在{chunk_path}/{file_id}/session.json，跨请求续传依赖该文件，请勿在上传期间清理chunk_path - 命名策略：合并时临时对象键为
{dirname}/{file_id}（扩展名合并时才确定），mergeChunk完成后统一 copy 改名。传入$options['file_hash']（整文件散列）则最终对象为{file_hash}.{ext}，否则为{file_id}.{ext} - 返回结构：与本地合并一致（
origin_name/save_name/save_path/url/unique_id/size/mime_type/extension）；云端无本地文件，mime_type取$options['mime_type']，默认application/octet-stream；unique_id为file_hash（未传时为file_id）
[!WARNING]
- 厂商对非末尾分片有最小尺寸要求：S3 ≥ 5MB、COS ≥ 1MB、OSS ≥ 100KB。默认
chunk_size5MB 满足全部厂商，调小需谨慎- 中断且未合并的云端 Multipart 会话（含已上传分片）会长期占用存储桶，本库不提供 abort 接口，请由业务侧调用厂商 API 中止，或为存储桶配置"未完成分片上传"生命周期清理规则
- 七牛云中途中断的本地暂存分片位于
chunk_path，同样需业务侧定期清理
🧪 代码质量
工具链：Mago（格式化 / lint / 静态分析）+ Pest（单元测试）
