shawnl/tencent-cos

Tencent COS SDK wrapper for PHP with Laravel support

v2.0.3 2025-12-04 07:34 UTC

Requires

• php: ^7.4|^8.0|^8.3
• illuminate/contracts: ^8.0|^9.0|^10.0|^11.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0
• qcloud/cos-sdk-v5: ^2.0

Requires (Dev)

• orchestra/testbench: ^6.0|^7.0|^8.0|^9.0
• phpunit/phpunit: ^9.0

MIT

• Shawn

• sdk
• laravel
• tencent
• cos

README

这个包为Laravel文件系统提供了腾讯云COS（云对象存储）适配器。

安装

composer require shawnl/tencent-cos

配置

在您的config/filesystems.php文件中添加以下配置：

'tencent-cos' => [
    'driver'      => 'tencent-cos',
    'region'      => env('COS_DEFAULT_REGION'),
    'credentials' => [
        'secret_id'  => env('COS_SECRET_ID'),
        'secret_key' => env('COS_SECRET_KEY'),
    ],
    'bucket'      => env('COS_DEFAULT_BUCKET'),
    'cdn_domain'  => env('COS_DEFAULT_CDN_DOMAIN'),
],

然后在您的.env文件中添加以下环境变量：

COS_DEFAULT_REGION=your-region
COS_SECRET_ID=your-secret-id
COS_SECRET_KEY=your-secret-key
COS_DEFAULT_BUCKET=your-bucket
COS_DEFAULT_CDN_DOMAIN= https://your-cdn-domain.com

使用方法

使用Laravel的Storage门面

文件上传

// 上传字符串内容
Storage::disk('tencent-cos')->put('path/to/file.jpg', $fileContents);

// 上传文件流
Storage::disk('tencent-cos')->put('path/to/file.pdf', fopen($pathToFile, 'r'));

// 上传并设置文件可见性
Storage::disk('tencent-cos')->put('path/to/public-file.jpg', $fileContents, 'public');

// 上传并设置内容类型
Storage::disk('tencent-cos')->put('path/to/file.json', json_encode($data), [
    'ContentType' => 'application/json'
]);

文件下载与读取

// 读取文件内容
$content = Storage::disk('tencent-cos')->get('path/to/file.txt');

// 获取文件流
$stream = Storage::disk('tencent-cos')->readStream('path/to/file.jpg');

// 下载文件到本地
Storage::disk('tencent-cos')->download('path/to/file.pdf');

文件管理

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

// 删除文件
Storage::disk('tencent-cos')->delete('path/to/file.jpg');

// 删除多个文件
Storage::disk('tencent-cos')->delete([
    'path/to/file1.jpg',
    'path/to/file2.jpg'
]);

// 移动文件
Storage::disk('tencent-cos')->move('path/to/old.jpg', 'path/to/new.jpg');

// 复制文件
Storage::disk('tencent-cos')->copy('path/to/source.jpg', 'path/to/destination.jpg');

目录操作

// 创建目录
Storage::disk('tencent-cos')->makeDirectory('path/to/new-directory');

// 删除目录
Storage::disk('tencent-cos')->deleteDirectory('path/to/directory');

// 列出目录内容
$files = Storage::disk('tencent-cos')->files('path/to/directory');

// 列出所有文件（包括子目录）
$allFiles = Storage::disk('tencent-cos')->allFiles('path/to/directory');

// 列出目录
$directories = Storage::disk('tencent-cos')->directories('path/to/directory');

文件信息与检查

// 检查文件是否存在
$exists = Storage::disk('tencent-cos')->exists('path/to/file.jpg');

// 检查目录是否存在
$dirExists = Storage::disk('tencent-cos')->directoryExists('path/to/directory');

// 获取文件大小
$size = Storage::disk('tencent-cos')->size('path/to/file.jpg');

// 获取文件MIME类型
$mimeType = Storage::disk('tencent-cos')->mimeType('path/to/file.jpg');

// 获取文件最后修改时间
$modified = Storage::disk('tencent-cos')->lastModified('path/to/file.jpg');

// 获取文件可见性
$visibility = Storage::disk('tencent-cos')->getVisibility('path/to/file.jpg');

// 设置文件可见性
Storage::disk('tencent-cos')->setVisibility('path/to/file.jpg', 'public');

默认磁盘配置

如果在config/filesystems.php中将default配置为tencent-cos，则可以直接省略disk('tencent-cos')，直接使用Storage::方法：

// 默认使用tencent-cos磁盘
Storage::put('file.jpg', $content);
$url = Storage::url('file.jpg');

主要功能

• ✅ 完整实现Laravel的Filesystem和Cloud接口
• ✅ 支持文件上传、下载、删除、移动、复制等操作
• ✅ 支持获取文件URL和临时URL
• ✅ 支持CDN域名配置
• ✅ 支持SSL访问
• ✅ 提供便捷的辅助函数
• ✅ 支持多Laravel版本（8.x - 11.x）

注意事项

1. 确保在使用前已在 config/filesystems.php 中正确配置阿里云OSS的访问凭证和存储桶信息
2. 使用临时URL时，确保当前服务器时间与OSS服务器时间同步，避免时间偏差导致链接失效
3. 建议将敏感配置（如访问密钥）存储在环境变量中，而不是直接硬编码在配置文件中
4. 使用CDN域名时，确保已在阿里云OSS控制台正确配置CDN加速
5. 本包完全依赖Laravel文件系统接口，不需要使用单独的辅助函数
6. 支持Laravel 11.x及以上版本

版本要求

• PHP >= 7.4
• Laravel >= 8.0
• aliyuncs/oss-sdk-php >= 2.6

许可证

MIT