# flysystem-cloud-obs

**Repository Path**: codeyunai/flysystem-cloud-obs

## Basic Information

- **Project Name**: flysystem-cloud-obs
- **Description**: 本适配器为 Flysystem 提供了与华为云 OBS（Object Storage Service）的集成，支持文件的上传、下载、删除、重命名等操作。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-25
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flysystem Cloud OBS 适配器

适用于 [League\Flysystem](https://flysystem.thephpleague.com/) 的华为云对象存储服务（OBS）适配器。

## 简介

本适配器为 Flysystem 提供了与华为云 OBS（Object Storage Service）的集成，支持文件的上传、下载、删除、重命名等操作。

## 系统要求

- PHP >= 7.2
- League\Flysystem ^1.1.10
- obs/esdk-obs-php ^3.22.6

## 安装

使用 Composer 安装：

```bash
composer require codeyunai/flysystem-cloud-obs
```

## 配置

### 基本配置

```php
use League\Flysystem\Filesystem;
use Codeyunai\FlysystemCloudObs\ObsAdapter;

$config = [
    'key'              => 'your-access-key-id',        // 必填：访问密钥 ID
    'secret'           => 'your-secret-access-key',    // 必填：访问密钥
    'bucket'           => 'your-bucket-name',          // 必填：桶名称
    'endpoint'         => 'obs.cn-south-2.myhuaweicloud.com', // 选填：OBS 服务端点，默认为华南2区
    'timeout'          => 3600,                        // 选填：超时时间（秒），默认 3600
    'connect_timeout'  => 10,                          // 选填：连接超时时间（秒），默认 10
    'is_cname'         => false,                       // 选填：是否使用自定义域名，默认 false
    'security_token'   => null,                        // 选填：安全令牌，用于临时访问凭证
];

$adapter = new ObsAdapter($config);
$filesystem = new Filesystem($adapter);
```

### 配置参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `key` | string | 是 | - | 华为云访问密钥 ID (Access Key ID) |
| `secret` | string | 是 | - | 华为云访问密钥 (Secret Access Key) |
| `bucket` | string | 是 | - | OBS 桶名称 |
| `endpoint` | string | 否 | `obs.cn-south-2.myhuaweicloud.com` | OBS 服务端点地址 |
| `timeout` | int | 否 | 3600 | 请求超时时间（秒） |
| `connect_timeout` | int | 否 | 10 | 连接超时时间（秒） |
| `is_cname` | bool | 否 | false | 是否使用自定义域名 |
| `security_token` | string | 否 | null | 临时访问凭证的安全令牌 |

## 基本用法

### 文件写入

```php
// 写入字符串内容
$filesystem->write('path/to/file.txt', 'Hello World');

// 写入文件流（支持大文件分段上传，每段 1MB）
$stream = fopen('/path/to/local/file.txt', 'r');
$filesystem->writeStream('path/to/file.txt', $stream);
fclose($stream);
```

### 文件读取

```php
// 读取文件内容
$contents = $filesystem->read('path/to/file.txt');

// 读取文件流
$stream = $filesystem->readStream('path/to/file.txt');
```

### 文件更新

```php
// 更新文件内容
$filesystem->update('path/to/file.txt', 'New content');

// 使用流更新文件
$stream = fopen('/path/to/local/file.txt', 'r');
$filesystem->updateStream('path/to/file.txt', $stream);
```

### 文件操作

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

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

// 重命名文件
$filesystem->rename('old/path.txt', 'new/path.txt');

// 复制文件
$filesystem->copy('source.txt', 'destination.txt');
```

### 获取文件信息

```php
// 获取文件元数据
$metadata = $filesystem->getMetadata('path/to/file.txt');

// 获取文件大小
$size = $filesystem->getSize('path/to/file.txt');

// 获取 MIME 类型
$mimetype = $filesystem->getMimetype('path/to/file.txt');

// 获取时间戳
$timestamp = $filesystem->getTimestamp('path/to/file.txt');
```

### 目录操作

```php
// 列出目录内容（非递归）
$contents = $filesystem->listContents('path/to/directory');

// 递归列出目录内容
$contents = $filesystem->listContents('path/to/directory', true);
```

### 访问权限管理

```php
// 设置文件为公开访问
$filesystem->setVisibility('path/to/file.txt', 'public');

// 设置文件为私有访问
$filesystem->setVisibility('path/to/file.txt', 'private');

// 获取文件访问权限
$visibility = $filesystem->getVisibility('path/to/file.txt');
```

## 高级功能

### 自定义配置选项

在写入或更新文件时，可以传递额外的配置选项：

```php
use League\Flysystem\Config;

$config = new Config([
    'Content-Type' => 'text/plain',
    'Content-Md5' => base64_encode(md5($contents, true)),
    'headers' => [
        'Cache-Control' => 'max-age=3600',
    ]
]);

$filesystem->write('path/to/file.txt', 'content', $config);
```

### 大文件上传

使用 `writeStream` 方法上传大文件时，适配器会自动使用分段上传（每段 1MB），这样可以：
- 提高上传效率
- 减少内存占用
- 支持断点续传（在失败时自动清理）

```php
$stream = fopen('/path/to/large/file.zip', 'r');
$filesystem->writeStream('uploads/large-file.zip', $stream);
fclose($stream);
```

## 注意事项

1. **权限配置**：确保您的华为云账号具有 OBS 桶的读写权限
2. **端点选择**：根据桶所在区域选择正确的 endpoint
3. **分段上传**：大文件上传时自动分段，每段 1MB
4. **错误处理**：所有操作失败时返回 `false`，请做好异常处理
5. **PHP 版本**：需要 PHP 7.2 或更高版本

## 常见端点地址

| 区域 | Endpoint |
|------|----------|
| 华北-北京一 | obs.cn-north-1.myhuaweicloud.com |
| 华北-北京四 | obs.cn-north-4.myhuaweicloud.com |
| 华东-上海一 | obs.cn-east-3.myhuaweicloud.com |
| 华南-广州 | obs.cn-south-1.myhuaweicloud.com |
| 华南-深圳 | obs.cn-south-2.myhuaweicloud.com |

更多端点地址请参考[华为云 OBS 文档](https://console.huaweicloud.com/apiexplorer/#/endpoint/OBS)。

## 许可证

MIT License

## 作者

Kevin

## 相关链接

- [Flysystem 官方文档](https://flysystem.thephpleague.com/)
- [华为云 OBS 文档](https://support.huaweicloud.com/obs/index.html)
- [华为云 OBS PHP SDK](https://github.com/huaweicloud/huaweicloud-sdk-php-obs)