Integrate MinIO with Webman Using tinywan/storage: Step‑by‑Step Guide

Overview

In modern microservice architecture, combining a high‑performance PHP framework with a distributed object storage can greatly improve efficiency and scalability. Webman is a high‑performance PHP microservice framework based on Workerman, offering resident memory and asynchronous processing.

MinIO is an open‑source, lightweight, S3‑compatible distributed object storage suitable for many file‑storage scenarios. This article shows how to integrate MinIO into Webman using the tinywan/storage extension, focusing on correct configuration and providing complete code examples.

Why Choose Webman and MinIO?

Webman Core Advantages

Resident memory : avoids the repeated loading of traditional PHP‑FPM, improving response speed.

High concurrency : supports asynchronous mechanisms, suitable for high‑traffic scenarios.

Lightweight and efficient : low resource consumption, fast development and deployment.

MinIO Unique Features

High throughput : supports massive file storage with excellent performance.

S3 compatibility : fully compatible with AWS S3 API, easy to integrate.

Distributed support : multi‑node deployment ensures high availability and data redundancy.

Lightweight deployment : can be quickly set up with Docker, fitting containerised environments.

Environment Preparation

PHP environment : PHP 7.4 or higher with Webman installed.

MinIO service : deploy MinIO via Docker or binary.

Dependencies : install the tinywan/storage extension to simplify MinIO operations.

Install Webman

composer create-project workerman/webman

Deploy MinIO

docker run -d -p 9000:9000 -p 9001:9001 \
 --name minio \
 -e "MINIO_ROOT_USER=admin" \
 -e "MINIO_ROOT_PASSWORD=admin1234" \
 minio/minio server /data --console-address ":9001"

After deployment, open http://localhost:9001 and log in with admin / admin1234 to create a bucket (e.g., my-bucket).

Install tinywan/storage

composer require tinywan/storage

Webman Integration with MinIO

Configure MinIO

The configuration file is config/plugin/tinywan/storage/app.php. Set the s3 section as follows:

<?php
return [
    'enable' => true,
    'storage' => [
        'default' => 's3',
        'single_limit' => 1024 * 1024 * 200,
        'total_limit'  => 1024 * 1024 * 200,
        'nums' => 10,
        'include' => [],
        'exclude' => [],
        's3' => [
            'adapter' => \Tinywan\Storage\Adapter\S3Adapter::class,
            'key'    => 'admin',
            'secret' => 'admin1234',
            'bucket' => 'my-bucket',
            'dirname'=> 'storage',
            'domain' => 'http://127.0.0.1:9000/my-bucket',
            'region' => 'us-east-1',
            'version'=> 'latest',
            'use_path_style_endpoint' => true,
            'endpoint'=> 'http://127.0.0.1:9000',
            'acl'    => 'public-read',
        ],
    ],
];

Key points: default set to s3 to use MinIO as the default storage. key and secret correspond to MinIO’s MINIO_ROOT_USER and MINIO_ROOT_PASSWORD. bucket is the name of the bucket created in MinIO. endpoint is the address of the MinIO service. domain is the URL prefix for accessing stored files. use_path_style_endpoint must be true for MinIO compatibility.

Create MinIO Service Class

Place MinIOService.php under app/service and encapsulate basic operations:

<?php
namespace app\service;

use Tinywan\Storage\Storage;

class MinIOService
{
    protected $storage;

    public function __construct()
    {
        $this->storage = Storage::disk('s3');
    }

    /** Upload a file to MinIO */
    public function uploadFile(string $filePath, string $key)
    {
        try {
            $result = $this->storage->put($key, file_get_contents($filePath), 'public-read');
            return $result ? $this->storage->url($key) : false;
        } catch (\Exception $e) {
            return false;
        }
    }

    /** Get a temporary signed URL */
    public function getFileUrl(string $key)
    {
        try {
            return $this->storage->temporaryUrl($key, now()->addMinutes(20));
        } catch (\Exception $e) {
            return false;
        }
    }
}

Implement File Upload Endpoint

Create FileController.php in app/controller:

<?php
namespace app\controller;

use app\service\MinIOService;
use support\Request;

class FileController
{
    /** File upload API */
    public function upload(Request $request)
    {
        $file = $request->file('file');
        if (!$file || !$file->isValid()) {
            return response()->json(['error' => 'Invalid file'], 400);
        }

        $minio = new MinIOService();
        $key = 'uploads/' . time() . '_' . $file->getClientOriginalName();
        $filePath = $file->getPathname();
        $url = $minio->uploadFile($filePath, $key);

        if ($url) {
            return response()->json(['url' => $url]);
        }
        return response()->json(['error' => 'Upload failed'], 500);
    }
}

Configure Route

Add the following route to config/route.php:

<?php
use support\Router;

Router::post('/file/upload', [app\controller\FileController::class, 'upload']);

Test the Upload

Use curl to test:

curl -X POST http://127.0.0.1:8787/file/upload -F "file=@/path/to/your/file.jpg"

On success the API returns the file’s access URL.

Conclusion

By using the tinywan/storage extension, Webman can efficiently integrate MinIO, enabling a high‑performance file‑management microservice. The article covered environment setup, configuration, service class, controller, routing, and testing, with special emphasis on the correct s3 settings in config/plugin/tinywan/storage/app.php.