jackillll/flysystem-qcloud-cos

Flysystem Adapter for Tencent Qcloud COS SDK V5

3.1.2 2025-09-13 06:44 UTC

Requires

• php: ^8.2
• ext-json: *
• guzzlehttp/guzzle: ^7.0
• illuminate/filesystem: ^12.0
• illuminate/support: ^12.0
• league/flysystem: ^3.0
• nesbot/carbon: ^3.0
• qcloud/cos-sdk-v5: ^2.0

Requires (Dev)

• orchestra/testbench: ^10.0
• phpunit/phpunit: ^11.0

MIT

• freyo

• qcloud
• flysystem-adapter
• qcloud-cos
• qcloud-sdk

README

Elegant Filesystem Adapter for Tencent Cloud Object Storage

Installation

Support Laravel/Lumen 12.x (PHP 8.2+) For older Laravel versions, please use v2.x Also supports standalone PHP projects

composer require "jackillll/flysystem-qcloud-cos:^3.0" -vvv

Usage

For Standalone PHP Projects (Recommended)

For non-Laravel projects, use the factory class for easy setup:

<?php
require_once 'vendor/autoload.php';

use Jackillll\Flysystem\QcloudCos\QcloudCosFactory;

// Minimal configuration
$config = [
    'region' => 'ap-guangzhou',
    'credentials' => [
        'appId' => 'your-app-id',
        'secretId' => 'your-secret-id',
        'secretKey' => 'your-secret-key',
    ],
    'bucket' => 'your-bucket-name',
];

// Create extended adapter (recommended)
$storage = QcloudCosFactory::createExtendedAdapter($config);

// Basic operations
$storage->put('hello.txt', 'Hello World!');
$content = $storage->get('hello.txt');
$url = $storage->url('hello.txt');
$storage->delete('hello.txt');

Available Factory Methods:

• QcloudCosFactory::createExtendedAdapter($config) - Creates extended adapter with Laravel-like methods
• QcloudCosFactory::createFilesystem($config) - Creates basic Flysystem instance
• QcloudCosFactory::createClient($config) - Creates COS client only
• QcloudCosFactory::validateConfig($config) - Validates configuration

See more examples in the /examples directory.

For Laravel Projects

Bootstrap

<?php
use Jackillll\Flysystem\QcloudCos\Adapters\QcloudCosAdapter;
use League\Flysystem\Filesystem;
use Qcloud\Cos\Client;

include __DIR__ . '/vendor/autoload.php';

// Configuration
$config = [
    'region' => 'ap-guangzhou',
    'credentials' => [
        'appId' => 'your-app-id',
        'secretId' => 'your-secret-id', 
        'secretKey' => 'your-secret-key',
    ],
    'bucket' => 'your-bucket',
    'cdn' => 'https://your-cdn-domain.com',
    'scheme' => 'https',
];

$client = new Client($config);
$adapter = new QcloudCosAdapter($client, $config);
$flysystem = new Filesystem($adapter, $config);

$config = [
    'region'          => 'ap-guangzhou',
    'credentials'     => [
        'appId'     => 'your-app-id',
        'secretId'  => 'your-secret-id',
        'secretKey' => 'your-secret-key',
        'token'     => null,
    ],
    'timeout'         => 60,
    'connect_timeout' => 60,
    'bucket'          => 'your-bucket-name',
    'cdn'             => '',
    'scheme'          => 'https',
    'read_from_cdn'   => false,
    'cdn_key'         => '',
    'encrypt'         => false,
];

$client     = new Client($config);
$adapter    = new Adapter($client, $config);
$filesystem = new Filesystem($adapter);

API

bool $flysystem->write('file.md', 'contents');

bool $flysystem->writeStream('file.md', fopen('path/to/your/local/file.jpg', 'r'));

bool $flysystem->update('file.md', 'new contents');

bool $flysystem->updateStram('file.md', fopen('path/to/your/local/file.jpg', 'r'));

bool $flysystem->rename('foo.md', 'bar.md');

bool $flysystem->copy('foo.md', 'foo2.md');

bool $flysystem->delete('file.md');

bool $flysystem->has('file.md');

string|false $flysystem->read('file.md');

array $flysystem->listContents();

array $flysystem->getMetadata('file.md');

int $flysystem->getSize('file.md');

string $flysystem->getUrl('file.md'); 

string $flysystem->getTemporaryUrl('file.md', date_create('2018-12-31 18:12:31')); 

string $flysystem->getMimetype('file.md');

int $flysystem->getTimestamp('file.md');

string $flysystem->getVisibility('file.md');

bool $flysystem->setVisibility('file.md', 'public'); //or 'private', 'default'

Full API documentation.

Use in Laravel

Laravel 12+ uses Package Auto-Discovery, so doesn't require you to manually add the ServiceProvider.

Driver Names

This package supports two driver names for backward compatibility:

• qcloud-cos (recommended for new projects)

Configuration

1. Configure config/filesystems.php with either driver:

'disks'=>[
    // Option 1: Using qcloud-cos driver (recommended)
    'qcloud-cos' => [
          'driver' => 'qcloud-cos',
          'region'          => env('QCLOUD_COS_REGION', 'ap-guangzhou'),
          'credentials'     => [
              'appId'     => env('QCLOUD_COS_APP_ID'),
              'secretId'  => env('QCLOUD_COS_SECRET_ID'),
              'secretKey' => env('QCLOUD_COS_SECRET_KEY'),
              'token'     => env('QCLOUD_COS_TOKEN'),
          ],
          'timeout'         => env('QCLOUD_COS_TIMEOUT', 60),
          'connect_timeout' => env('QCLOUD_COS_CONNECT_TIMEOUT', 60),
          'bucket'          => env('QCLOUD_COS_BUCKET'),
          'cdn'             => env('QCLOUD_COS_CDN'),
          'scheme'          => env('QCLOUD_COS_SCHEME', 'https'),
          'read_from_cdn'   => env('QCLOUD_COS_READ_FROM_CDN', false),
          'cdn_key'         => env('QCLOUD_COS_CDN_KEY'),
          'encrypt'         => env('QCLOUD_COS_ENCRYPT', false),
    ],
    

],

1. Configure .env:

Use in Lumen

1. Add the following code to your bootstrap/app.php:

$app->singleton('filesystem', function ($app) {
    $app->alias('filesystem', Illuminate\Contracts\Filesystem\Factory::class);
    return $app->loadComponent(
        'filesystems',
        Illuminate\Filesystem\FilesystemServiceProvider::class,
        'filesystem'
    );
});

1. And this:

$app->register(Freyo\Flysystem\QcloudCOS\ServiceProvider::class);

1. Configure .env:

Usage

$disk = Storage::disk('qcloud-cos');

// create a file
$disk->put('avatars/1', $fileContents);

// check if a file exists
$exists = $disk->has('file.jpg');

// get timestamp
$time = $disk->lastModified('file1.jpg');

// copy a file
$disk->copy('old/file1.jpg', 'new/file1.jpg');

// move a file
$disk->move('old/file1.jpg', 'new/file1.jpg');

// get file contents
$contents = $disk->read('folder/my_file.txt');

// get url
$url = $disk->url('new/file1.jpg');
$temporaryUrl = $disk->temporaryUrl('new/file1.jpg', Carbon::now()->addMinutes(5));

// create a file from remote(plugin)
$disk->putRemoteFile('avatars/1', 'http://example.org/avatar.jpg');
$disk->putRemoteFileAs('avatars/1', 'http://example.org/avatar.jpg', 'file1.jpg');

// refresh cdn cache(plugin)
$disk->cdn()->refreshUrl(['http://your-cdn-host/path/to/avatar.jpg']);
$disk->cdn()->refreshDir(['http://your-cdn-host/path/to/']);
$disk->cdn()->pushUrl(['http://your-cdn-host/path/to/avatar.jpg']);
$disk->cdn()->refreshOverseaUrl(['http://your-cdn-host/path/to/avatar.jpg']);
$disk->cdn()->refreshOverseaDir(['http://your-cdn-host/path/to/']);
$disk->cdn()->pushOverseaUrl(['http://your-cdn-host/path/to/avatar.jpg']);

// cdn url signature(plugin)
$url = 'http://www.test.com/1.mp4';
$disk->cdn()->signatureA($url, $key = null, $timestamp = null, $random = null, $signName = 'sign');
$disk->cdn()->signatureB($url, $key = null, $timestamp = null);
$disk->cdn()->signatureC($url, $key = null, $timestamp = null);
$disk->cdn()->signatureD($url, $key = null, $timestamp = null, $signName = 'sign', $timeName = 't');

// tencent captcha(plugin)
$disk->tcaptcha($aid, $appSecretKey)->verify($ticket, $randStr, $userIP);

// get federation token(plugin)
$disk->getFederationToken($path = '*', $seconds = 7200, Closure $customPolicy = null, $name = 'cos')
$disk->getFederationTokenV3($path = '*', $seconds = 7200, Closure $customPolicy = null, $name = 'cos')

// tencent image process(plugin)
$disk->cloudInfinite()->imageProcess($objectKey, array $picOperations);
$disk->cloudInfinite()->contentRecognition($objectKey, array $contentRecognition);

Full API documentation.

Regions & Endpoints

Official Documentation

License

The MIT License (MIT). Please see License File for more information.