larva/laravel-flysystem-cos

This is a Flysystem adapter for the Tencent COS.

2.1.1 2026-07-24 07:23 UTC

Requires

• php: ^8.2
• laravel/framework: ^12.0|^13.0
• larva/flysystem-cos: ^1.0
• league/flysystem: ^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.6

MIT

• Flysystem
• tencent
• cos
• Larva

Published on Packagist.org on 2026-07-24 07:24 UTC

README

适用于 Laravel 的腾讯云 COS（对象存储）适配器，基于 Flysystem v3 封装，完整支持腾讯云 COS V5 SDK 的所有方法和操作。

特性

• 基于 Flysystem v3，与 Laravel 文件系统无缝集成
• 支持公共 URL 生成与私有文件临时访问链接（临时 URL）
• 支持 CDN 加速域名配置
• 自动注册服务提供者（Laravel Package Discovery）
• 支持 Laravel 12 / 13

环境要求

• PHP >= 8.2
• Laravel >= 12.0
• League/Flysystem >= 3.0

安装

composer require larva/laravel-flysystem-cos -vv

配置

安装完成后，修改配置文件 config/filesystems.php，在 disks 中添加一个磁盘配置：

'cos' => [
    'driver' => 'cos',
    // 'endpoint' => env('TENCENT_COS_ENDPOINT'), // 接入点，留空即可
    'region' => env('TENCENT_COS_REGION'), // 存储桶所在区域，如 ap-guangzhou
    'credentials' => [ // 认证凭证
        'appId' => env('TENCENT_COS_APP_ID'), // 存储桶名称后缀，如 1258464748
        'secretId' => env('TENCENT_COS_SECRET_ID'),
        'secretKey' => env('TENCENT_COS_SECRET_KEY'),
        'token' => env('TENCENT_COS_TOKEN'), // 临时密钥时使用，可选
    ],
    'bucket' => env('TENCENT_COS_BUCKET'), // 存储桶名称
    'root' => env('COS_PREFIX'), // 存储路径前缀，可选
    'url' => env('TENCENT_COS_URL'), // CDN 加速域名，可选
    // 以下均可省略
    'scheme' => 'https', // 协议头，默认 http
    'timeout' => 3600,
    'connect_timeout' => 3600,
    'ip' => null,
    'port' => null,
    'domain' => null,
    'proxy' => null,
    'encrypt' => null,
],

如果需要将 COS 设为默认存储驱动，修改 default 配置：

'default' => 'cos',

在 .env 文件中配置对应的环境变量：

TENCENT_COS_REGION=ap-guangzhou
TENCENT_COS_APP_ID=1258464748
TENCENT_COS_SECRET_ID=your-secret-id
TENCENT_COS_SECRET_KEY=your-secret-key
TENCENT_COS_TOKEN=
TENCENT_COS_BUCKET=your-bucket-name
COS_PREFIX=
TENCENT_COS_URL=https://cdn.example.com

使用方法

基本操作

使用方式与 Laravel 文件系统一致，详细文档请参考 Laravel 文件系统文档。

use Illuminate\Support\Facades\Storage;

// 获取 COS 磁盘实例
$disk = Storage::disk('cos');

// 写入文件
$disk->put('path/to/file.txt', '文件内容');

// 读取文件
$contents = $disk->get('path/to/file.txt');

// 检查文件是否存在
$exists = $disk->exists('path/to/file.txt');

// 删除文件
$disk->delete('path/to/file.txt');

// 上传本地文件
$disk->putFile('uploads', new \Illuminate\Http\UploadedFile($path, $filename));

获取文件 URL

// 获取公共文件的访问 URL
$url = Storage::disk('cos')->url('path/to/file.jpg');

// 获取私有文件的临时访问 URL（有效期 5 分钟）
$tempUrl = Storage::disk('cos')->temporaryUrl(
    'path/to/private-file.pdf',
    now()->addMinutes(30)
);

获取 COS 客户端

如需直接操作腾讯云 COS SDK，可获取底层客户端实例：

$client = Storage::disk('cos')->getClient();

// 使用 COS SDK 直接操作
$result = $client->listObjects([
    'Bucket' => 'your-bucket-name',
    'Prefix' => 'uploads/',
]);

License

MIT