简单易用多文件上传插件

原创已于 2025-12-26 13:47:40 修改 · 116 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#PHP #WEBMAN

于 2025-12-26 13:46:33 首次发布

WEBMAN 专栏收录该内容

14 篇文章

订阅专栏

安装

composer require tinywan/storage

配置文件

/config/plugin/tinywan/storage/app.php

调用案例

#[Apidoc\Title("文件上传")]
#[Apidoc\Url("/webapi/common/upload")]
#[Apidoc\Method("POST,GET")]
#[Apidoc\ParamType("formdata")]
#[Apidoc\Param("file", type: "file", require: true, default: "", desc: "文件")]
#[Apidoc\Returned("origin_name", type: "string", default: "u=3019768837,3832590544&fm=253&fmt=auto&app=138&f=JPEG.webp", desc: "文件原名")]
#[Apidoc\Returned("save_name", type: "string", default: "593f53411eb2e08c28dd0f15b555b7dc0bf83aae.webp", desc: "存储后文件名")]
#[Apidoc\Returned("save_path", type: "string", default: "E:\\phpstudy_pro\\WWW\\QianYi\\Dapp\\mining\\public/uploads/20240222\\593f53411eb2e08c28dd0f15b555b7dc0bf83aae.webp", desc: "存储路径")]
#[Apidoc\Returned("url", type: "string", default: "/uploads/20240222\\593f53411eb2e08c28dd0f15b555b7dc0bf83aae.webp", desc: "展示路径")]
#[Apidoc\Returned("extension", type: "string", default: "webp", desc: "图片后缀")]
#[RequestMapping(["/upload"], methods: ['GET', 'POST', 'OPTIONS'])]
public function upload(Request $request): Response
{
    try {
        $res = Storage::uploadFile();
    }catch (StorageException $e){
        return error(lang($request,$e->getMessage()));
    }
    return success(lang($request,'操作成功'),$res[0]);
}

接入文档

## 基本用法

```php
$res = Tinywan\Storage\Storage::uploadFile();
var_dump(json_encode($res));
```
> ~~`v1.0.0` 版本之后不需要调用此方法`Tinywan\Storage\Storage::config()` 初始化，会自动初始化，默认为配置文件`app.php`默认配置`default`配置上传适配器。~~

### 上传成功信息
```json
[
    {
        "key": "webman",
        "origin_name": "常用编程软件和工具.xlsx",
        "save_name": "03414c9bdaf7a38148742c87b96b8167.xlsx",
        "save_path": "runtime/storage/03414c9bdaf7a38148742c87b96b8167.xlsx",
        "save_path": "/var/www/webman-admin/public/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/tinywan/storage/app.php`配置文件中配置上传根目录，例如：

```php
'local' => [
    'adapter' => \Tinywan\Storage\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

#### 阿里云对象存储

```php
composer require aliyuncs/oss-sdk-php
```
#### 腾讯云对象存储

```php
composer require qcloud/cos-sdk-v5
```

#### 七牛云云对象存储

```php
composer require qiniu/php-sdk
```

#### 亚马逊（S3）对象存储

```php
composer require league/flysystem-aws-s3-v3
```

## 上传Base64图片

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

#### 请求参数

```json
{
    "extension": "png",
    "base64": "data:image/jpeg;base64,/9j/4AAQSkxxxxxxxxxxxxZJRgABvtyQBIr/MPTPTP/2Q=="
}
```
#### 请求案例（阿里云）

```php
public function upload(Request $request)
{
    $base64 = $request->post('base64');
    $response = \Tinywan\Storage\Storage::disk(\Tinywan\Storage\Storage::MODE_OSS, false)->uploadBase64($base64,'png');
    var_dump($response);
}
```
> ~~`v1.0.0` 版本之后不需要调用此方法`Tinywan\Storage\Storage::config()` 初始化，会自动初始化，默认为配置文件`app.php`默认配置`default`配置上传适配器。~~

#### 响应参数
```json
{
	"save_path": "storage/20220402213639624851671439e.png",
	"url": "http://webman.oss.tinywan.com/storage/20220402213639624851671439e.png",
	"unique_id": "20220402213639624851671439e",
	"size": 11802,
	"extension": "png"
}
```
## 上传服务端文件

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

#### 请求案例（阿里云）

```php
$serverFile = runtime_path() . DIRECTORY_SEPARATOR . 'storage/webman.png';
$res = \Tinywan\Storage\Storage::disk(\Tinywan\Storage\Storage::MODE_OSS, false)->uploadServerFile($serverFile);
```
> ~~`v1.0.0` 版本之后不需要调用此方法`Tinywan\Storage\Storage::config()` 初始化，会自动初始化，默认为配置文件`app.php`默认配置`default`配置上传适配器。~~


#### 响应参数

```json
{
	"origin_name": "/var/www/webman-admin/runtime/storage/webman.png",
	"save_path": "storage/6edf04d7c26f020cf5e46e6457620220402213414.png",
	"url": "http://webman.oss.tinywan.com/storage/6ed9ffd54d0df57620220402213414.png",
	"unique_id": "6edf04d7c26f020cf5e46e6403213414",
	"size": 3505604,
	"extension": "png"
}
```