# tencent-cos

**Repository Path**: lsz_mo/tencent-cos

## Basic Information

- **Project Name**: tencent-cos
- **Description**: 腾讯cos 上传，可以使用系统Store::put()方式上传
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-08
- **Last Updated**: 2025-11-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 腾讯云COS适配器 for Laravel

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

## 安装

```bash
composer require shawnl/tencent-cos
```

## 配置

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

```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`文件中添加以下环境变量：
```dotenv
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门面

#### 文件上传

```php
// 上传字符串内容
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'
]);
```

#### 文件下载与读取

```php
// 读取文件内容
$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');
```

#### 文件管理

```php
// 获取文件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');
```

#### 目录操作

```php
// 创建目录
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');
```

#### 文件信息与检查

```php
// 检查文件是否存在
$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::方法：

```php
// 默认使用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