How to Use Tinywan Storage for Multi‑File Uploads with Local, OSS, COS, and Qiniu

Introduction

The Tinywan Storage plugin offers a unified API for uploading multiple files in PHP. It supports local storage and three major cloud object storage services: Alibaba Cloud OSS, Tencent Cloud COS, and Qiniu.

Installation

composer require tinywan/storage

Basic Usage

Tinywan\Storage\Storage::config(); // initialize, default driver is local
$res = Tinywan\Storage\Storage::uploadFile();
var_dump(json_encode($res));

On success the method returns a JSON object containing the following fields:

key : upload file key (e.g., webman)

origin_name : original file name (e.g., example.xlsx)

save_name : stored file name generated by the plugin (e.g., 03414c9bdaf7a38148742c87b96b8167.xlsx)

save_path : relative path on the server (e.g., runtime/storage/03414c9bdaf7a38148742c87b96b8167.xlsx)

url : public URL for accessing the file (e.g., /storage/fd2d472da56c71a6da0a5251f5e1b586.png)

unique_id : unique identifier derived from the file name (e.g., 03414c9bdaf7a38148742c87b96b8167)

size : file size in bytes (e.g., 15050)

mime_type : MIME type (e.g.,

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

)

extension : file extension (e.g., xlsx)

If the upload fails, a StorageException is thrown.

Cloud SDK Support

Install the corresponding SDK for each cloud driver before using it:

Alibaba Cloud OSS: composer require aliyuncs/oss-sdk-php Tencent Cloud COS: composer require qcloud/cos-sdk-v5 Qiniu:

composer require qiniu/php-sdk

Upload Rules & Configuration

By default files are stored under runtime/storage with a SHA‑1 based filename. To make files directly accessible, set the storage mode to public.

The configuration file config/plugin/tinywan/storage/pp.php defines the root directory for each driver. Example for the local driver:

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

Files stored with the public mode can be accessed via a URL such as http://127.0.0.1:8787/storage/yourfile.png .

Upload Validation

The plugin provides a validation class to limit size, count, and allowed extensions. Configurable fields are:

single_limit : maximum size per file (default 1024 * 1024 * 200 bytes, i.e., 200 MB)

total_limit : maximum cumulative size of all files (default 200 MB)

nums : maximum number of files per request (default 10)

include : whitelist of allowed extensions (e.g., ['xlsx','pdf'])

exclude : blacklist of disallowed extensions (e.g., ['png','jpg'])

Base64 Image Upload

Base64 encoding allows an image to be sent as a string instead of a file URL. Typical use cases include electronic signatures, facial‑recognition snapshots, and canvas‑based avatar capture.

Request Parameters

{
    "base64": "data:image/jpeg;base64,/9j/4AAQSk..."
}

Example (Alibaba Cloud OSS)

public function upload(Request $request)
{
    $base64 = $request->post('base64');
    // First argument selects the storage driver, second argument indicates the file is not a local file
    Tinywan\Storage\Storage::config(Storage::MODE_OSS, false);
    $result = Tinywan\Storage\Storage::uploadBase64($base64);
    var_dump($result);
}

The response contains save_path , url , unique_id , size and extension .

{
    "save_path": "storage/20220402213639624851671439e.png",
    "url": "http://webman.oss.tinywan.com/storage/20220402213639624851671439e.png",
    "unique_id": "20220402213639624851671439e",
    "size": 11802,
    "extension": "png"
}

Server File Upload

This method uploads files that already exist on the server (e.g., generated reports or log backups) to a cloud bucket.

Example (Alibaba Cloud OSS)

// Configure the driver; second argument must be false for server files
Tinywan\Storage\Storage::config(Storage::MODE_OSS, false);
$localFile = runtime_path() . DIRECTORY_SEPARATOR . 'storage/webman.png';
$res = Tinywan\Storage\Storage::uploadServerFile($localFile);
var_dump($res);

{
    "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"
}

The uploaded file can be accessed directly via the returned url .