How to Integrate Huawei OBS into Your Laravel App Using Flysystem

Are you building a Laravel application and want to use Huawei Cloud Object Storage (OBS) instead of AWS S3 or local disks? Whether you’re optimizing for cost, compliance, or infrastructure locality, Huawei OBS is a powerful, S3-compatible option.

In this hands-on tutorial, you’ll learn how to integrate Huawei OBS with Laravel’s storage system using the open-source laravel-flysystem-huawei-obs package.

🧩 What You’ll Need

• Laravel 9, 10, 11, or 12
• PHP 8.1 or newer
• Huawei Cloud account with OBS enabled
• Access Key and Secret Key
• An OBS bucket and endpoint (e.g., obs.cn-east-3.myhuaweicloud.com)

📦 Step 1: Install the OBS Flysystem Adapter

Install the package using Composer:

composer require mubbi/laravel-flysystem-huawei-obs

⚙️ Step 2: Configure Your Disk in Laravel

Open your config/filesystems.php file and add a new disk configuration for OBS:

'disks' => [
    'huawei-obs' => [
        'driver' => 'huawei-obs',
        'key' => env('HUAWEI_OBS_ACCESS_KEY_ID'),
        'secret' => env('HUAWEI_OBS_SECRET_ACCESS_KEY'),
        'bucket' => env('HUAWEI_OBS_BUCKET'),
        'endpoint' => env('HUAWEI_OBS_ENDPOINT'),
        'region' => env('HUAWEI_OBS_REGION'),
        'prefix' => env('HUAWEI_OBS_PREFIX'),
        'security_token' => env('HUAWEI_OBS_SECURITY_TOKEN'),
        'visibility' => 'private',
        'throw' => false,
        'http_client' => [
            'timeout' => 30,
            'connect_timeout' => 10,
            'verify' => true,
            'proxy' => null,
            'headers' => [],
        ],
        'retry_attempts' => 3,
        'retry_delay' => 1,
        'logging_enabled' => false,
        'log_operations' => false,
        'log_errors' => true,
    ],
],

Then update your .env file accordingly:

HUAWEI_OBS_ACCESS_KEY_ID=your_access_key_id
HUAWEI_OBS_SECRET_ACCESS_KEY=your_secret_access_key
HUAWEI_OBS_BUCKET=your_bucket_name
HUAWEI_OBS_ENDPOINT=https://obs.cn-north-1.myhuaweicloud.com
HUAWEI_OBS_REGION=cn-north-1
HUAWEI_OBS_PREFIX=optional_prefix
HUAWEI_OBS_SECURITY_TOKEN=your_security_token_for_temporary_credentials

📂 Step 3: Use OBS Like Any Other Laravel Disk

With the OBS disk configured, you can now use it via the Storage facade:

use Illuminate\Support\Facades\Storage;

// Upload a file
Storage::disk('huawei-obs')->put('docs/manual.pdf', file_get_contents($file));

// Retrieve a file
$content = Storage::disk('huawei-obs')->get('docs/manual.pdf');

// Generate a public URL
$url = Storage::disk('huawei-obs')->url('docs/manual.pdf');

🔐 Step 4: Generate Private Access URLs (Optional)

If your bucket is private, you can generate expiring download URLs:

use Mubbi\LaravelFlysystemHuaweiObs\ObsStorageAdapter;

$disk = Storage::disk('huawei-obs');
$adapter = $disk->getAdapter();

$url = $adapter->privateDownloadUrl('docs/secret.pdf', now()->addMinutes(10));

📤 Step 5: Generate Upload Tokens for Frontend Uploads (Optional)

Need to let users upload directly to OBS from the browser?

$token = $adapter->getUploadToken('uploads/images/', 3600, [
    'content-length-range' => [0, 10485760], // limit size to 10MB
]);

Use this token in your frontend form or JavaScript uploader.

🧪 Step 6: Test It Out

Use a quick Artisan route for verification:

Route::get('/upload-test', function () {
    Storage::disk('huawei-obs')->put('demo/test.txt', 'Hello OBS from Laravel!');
    return 'Uploaded!';
});

Visit /upload-test in your browser. Then check your Huawei OBS console to confirm the upload.

🔍 Troubleshooting Tips

🧠 Pro Tips

• ✅ Use Storage::disk('huawei-obs')->exists($path) to check if a file exists.
• ✅ Use getMetadata, lastModified, copy, move, and other native Laravel methods with OBS.
• ✅ Use Laravel Horizon or queues to handle OBS uploads in the background.
• ✅ Leverage OBS CNAME support to speed up file delivery through CDN.

📌 Conclusion

Integrating Huawei OBS into a Laravel app has never been easier. Thanks to the laravel-flysystem-huawei-obs adapter, you can treat OBS like any other Laravel disk. Whether you're scaling globally, building for Huawei Cloud customers, or diversifying from AWS, this package keeps your code clean and maintainable.

👉 Get started today: github.com/mubbi/laravel-flysystem-huawei-obs