raingad / webman-storage

0.1.0 2026-10-17 16:22 UTC

Requires

• php: >=7.2
• workerman/webman-framework: ^1.2.1||^2.0

Requires (Dev)

• aliyuncs/oss-sdk-php: ^2.4
• friendsofphp/php-cs-fixer: ^3.6
• league/flysystem-aws-s3-v3: ^1.0
• phpstan/phpstan: ^1.4
• phpunit/phpunit: ^9.5
• qcloud/cos-sdk-v5: ^2.5
• qiniu/php-sdk: ^7.4
• workerman/webman: ^1.0

Suggests

• aliyuncs/oss-sdk-php: Required when using the Aliyun OSS adapter (^2.4).
• league/flysystem-aws-s3-v3: Required when using the AWS S3 adapter (^1.0).
• qcloud/cos-sdk-v5: Required when using the Tencent COS adapter (^2.5).
• qiniu/php-sdk: Required when using the Qiniu adapter (^7.4).

MIT

• Raingad
• ShaoBo Wan(無尘)

• filesystem
• storage
• s3
• upload
• oss
• qiniu
• cos
• webman

Published on Packagist.org on 2026-10-17 16:24 UTC

README

本插件基于 tinywan/storage 修改，在原版基础上做了如下调整：

• 本地储存支持上传 Base64 图片
• 本地储存支持上传服务器文件（相当于服务器转存），保持 uploadServerFile 方法的一致性
• 统一 Base64 图片上传的返回参数
• 增加各个储存适配器的删除文件方法

感谢原作者 Tinywan(ShaoBo Wan)。本项目遵循 MIT 协议，LICENSE 中保留了原作者版权声明。

特性

云端	多文件上传	Base64图片上传	服务器文件上传
🍏 本地	✅	✅	✅
🍓 阿里云	✅	✅	✅
🍋 腾讯云	✅	✅	✅
🍇 七牛云	✅	✅	✅
🍇 亚马逊（S3）	✅	✅	✅

安装

composer require raingad/webman-storage

安装后插件会自动发布配置文件到 config/plugin/raingad/webman-storage/app.php。

基本用法

$res = \Raingad\WebmanStorage\Storage::uploadFile();
var_dump(json_encode($res));

上传成功信息

[
    {
        "key": "webman",
        "origin_name": "常用编程软件和工具.xlsx",
        "save_name": "03414c9bdaf7a38148742c87b96b8167.xlsx",
        "save_path": "runtime/storage/03414c9bdaf7a38148742c87b96b8167.xlsx",
        "url": "/storage/fd2d472da56c71a6da0a5251f5e1b586.png",
        "uniqid ": "03414c9bdaf7a38148742c87b96b8167",
        "size": 15050,
        "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "extension": "xlsx"
    }
]

失败时抛出 StorageAdapterException 异常。

成功响应字段

字段	描述	示例值
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	uniqid	03414c9bdaf7a38148742c87b96b8167
size	文件大小	15050（字节）
mime_type	文件类型	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
extension	文件扩展名	xlsx

上传规则

默认情况下是上传到本地服务器，会在 runtime/storage 目录下面生成以当前日期为子目录、以文件流的 sha1 编码为文件名的文件，例如：

runtime/storage/fd2d472da56c71a6da0a5251f5e1b586.png

如果你希望上传的文件可以直接访问或下载，可以使用 public 存储方式。

你可以在 config/plugin/raingad/webman-storage/app.php 配置文件中配置上传根目录，例如：

'local' => [
    'adapter' => \Raingad\WebmanStorage\Adapter\LocalAdapter::class,
    'root' => public_path() . '/storage',
],

浏览器访问：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：

阿里云对象存储

composer require aliyuncs/oss-sdk-php

腾讯云对象存储

composer require qcloud/cos-sdk-v5

七牛云云对象存储

composer require qiniu/php-sdk

亚马逊（S3）对象存储

composer require league/flysystem-aws-s3-v3

上传 Base64 图片

使用场景： 前端直接截图（头像、Canvas 等），将 Base64 数据流的图片直接上传到云端。

请求参数

{
    "extension": "png",
    "base64": "data:image/jpeg;base64,/9j/4AAQSkxxxxxxxxxxxxZJRgABvtyQBIr/MPTPTP/2Q=="
}

请求案例（阿里云）

public function upload(Request $request)
{
    $base64 = $request->post('base64');
    $response = \Raingad\WebmanStorage\Storage::disk(\Raingad\WebmanStorage\Storage::MODE_OSS, false)->uploadBase64($base64, 'png');
    var_dump($response);
}

响应参数

{
    "save_path": "storage/20220402213639624851671439e.png",
    "url": "https://cdn.example.com/storage/20220402213639624851671439e.png",
    "unique_id": "20220402213639624851671439e",
    "size": 11802,
    "extension": "png"
}

上传服务端文件

使用场景： 服务端导出文件需要上传到云端存储，或者临时下载文件存储。

请求案例（阿里云）

$serverFile = runtime_path() . DIRECTORY_SEPARATOR . 'storage/webman.png';
$res = \Raingad\WebmanStorage\Storage::disk(\Raingad\WebmanStorage\Storage::MODE_OSS, false)->uploadServerFile($serverFile);

响应参数

和普通文件上传统一响应参数格式。

{
    "key": "webman",
    "origin_name": "常用编程软件和工具.xlsx",
    "save_name": "03414c9bdaf7a38148742c87b96b8167.xlsx",
    "save_path": "/var/www/webman-admin/public/storage/03414c9bdaf7a38148742c87b96b8167.xlsx",
    "url": "https://cdn.example.com/storage/03414c9bdaf7a38148742c87b96b8167.xlsx",
    "uniqid ": "03414c9bdaf7a38148742c87b96b8167",
    "size": 15050,
    "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "extension": "xlsx"
}

开发

vendor/bin/phpstan analyse src
vendor/bin/php-cs-fixer fix src
vendor/bin/phpunit