Master PHP File Uploads with Tinywan/Storage: Cloud, Base64, and Server Options

Overview

The Tinywan/Storage PHP package provides a unified API for uploading files to local storage or various cloud services (private cloud, Alibaba Cloud OSS, Tencent Cloud COS, Qiniu). It supports single‑file, multi‑file, Base64 image, and server‑side file uploads.

Installation

composer require tinywan/storage

Basic Usage

use Tinywan\Storage\Storage;
$res = Storage::uploadFile();
var_dump(json_encode($res));

On success the method returns a JSON object containing fields such as key , origin_name , save_name , save_path , url , unique_id , size , mime_type , and extension .

Response Fields

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

origin_name : original filename (e.g., example.xlsx)

save_name : stored filename generated from SHA‑1 hash

save_path : relative path on the storage backend

url : public URL for accessing the file

unique_id : unique identifier derived from the hash

size : file size in bytes

mime_type : MIME type of the file

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

Upload Rules & Configuration

By default files are stored under runtime/storage with sub‑directories based on the current date and filenames generated from the file’s SHA‑1 hash. To expose files publicly, set the storage mode to public and configure the root directory in config/plugin/tinywan/storage/app.php:

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

Public files can be accessed via a URL such as http://127.0.0.1:8787/storage/your_file.png .

Validation Options

single_limit

: maximum size per file (default 200 MiB) total_limit: total size for all files in a request (default 200 MiB) nums: maximum number of files (default 10) include: whitelist of allowed extensions (e.g., ['xlsx','pdf']) exclude: blacklist of disallowed extensions (e.g., ['png','jpg'])

Supported Cloud SDKs

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

composer require qiniu/php-sdk

Base64 Image Upload

Use case: Front‑end captures a screenshot or canvas image and sends the Base64 string directly to the server.

Request Payload

{
  "extension": "png",
  "base64": "data:image/jpeg;base64,/9j/..."
}

Example (Alibaba Cloud)

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

Typical Response

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

Server‑Side File Upload

Use case: Upload files generated on the server (e.g., export reports) to cloud storage.

Example (Alibaba Cloud)

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

Response

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