README

基于 League\Flysystem 的火山引擎 TOS (字节跳动对象存储) 适配器。

特性

完全兼容 Flysystem v3.0+ API
支持所有基本的文件操作（读取、写入、删除、复制、移动等）
支持文件和目录的可见性设置
支持流式上传和下载
支持文件元数据操作
内置错误处理和异常管理
对 Swoole / Hyperf 协程环境安全，支持注入协程 handler

安装

通过 Composer 安装：

composer require jiangwang/flysystem-tos

要求

PHP >= 8.0
League\Flysystem ^3.0
ext-json
guzzlehttp/guzzle ^7.8
league/mime-type-detection ^1.16

使用方法

基本配置

<?php

use League\Flysystem\Filesystem;
use Jiangwang\FlysystemTos\TosAdapter;

// 配置 TOS 客户端
$config = [
    'region' => 'cn-beijing',
    'endpoint' => 'https://tos-cn-beijing.volces.com', // 已知 region 时可省略，SDK 会自动补默认 Endpoint
    'ak' => 'your-access-key-id',
    'sk' => 'your-access-key-secret',
    'bucket' => 'your-bucket-name',
    // 可选配置
    'securityToken' => 'your-security-token', // 临时凭证
    'connectionTimeout' => 30000,
    'socketTimeout' => 30000,
];

// 创建适配器和文件系统
$adapter = new TosAdapter($config);
$filesystem = new Filesystem($adapter);

Hyperf / Swoole 协程环境

适配器对 Swoole 协程安全：默认使用每请求独立句柄的 CurlHandler，不会在协程内共享 curl_multi 句柄，也不会切换 Swoole Runtime Hook，可安全用于 Hyperf 的并发协程任务。

在 Hyperf 下推荐注入 hyperf/guzzle 的 CoroutineHandler，以获得连接池复用与更低的请求开销：

<?php

use Hyperf\Guzzle\CoroutineHandler;
use Jiangwang\FlysystemTos\TosAdapter;

$config = [
    'region' => 'cn-beijing',
    'ak' => 'your-access-key-id',
    'sk' => 'your-access-key-secret',
    'bucket' => 'your-bucket-name',
    'handler' => new CoroutineHandler(), // 可选：协程 handler，带连接池复用
];

$adapter = new TosAdapter($config);

注意事项：

不传 handler 时使用默认 CurlHandler，每次请求新建/关闭连接（无连接复用），高频上传场景建议注入 CoroutineHandler。
分片上传（uploadFile）的并发数在当前协程内是串行执行的；需要真正并行时，请在宿主层使用多协程（如 Hyperf 的 Parallel）并发发起上传。

文件操作

写入文件

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

// 写入文件流
$stream = fopen('local/file.txt', 'r');
$filesystem->writeStream('path/to/file.txt', $stream);

// 设置文件可见性
$filesystem->write('path/to/file.txt', 'content', [
    'visibility' => 'public' // 或 'private'
]);

读取文件

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

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

文件信息

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

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

// 获取文件最后修改时间
$timestamp = $filesystem->lastModified('path/to/file.txt');

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

// 获取文件可见性
$visibility = $filesystem->visibility('path/to/file.txt');

文件管理

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

// 移动文件
$filesystem->move('source/file.txt', 'destination/file.txt');

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

目录操作

// 创建目录
$filesystem->createDirectory('path/to/directory');

// 检查目录是否存在
$exists = $filesystem->directoryExists('path/to/directory');

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

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

// 删除目录
$filesystem->deleteDirectory('path/to/directory');

可见性设置

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

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

配置选项

适配器支持以下配置选项：

配置项	类型	必需	描述
`region`	string	是	TOS 服务区域
`endpoint`	string	否	TOS 服务端点；已知 region 未传时使用 SDK 内置默认 Endpoint
`ak`	string	是	访问密钥 ID
`sk`	string	是	访问密钥密码
`bucket`	string	是	存储桶名称
`securityToken`	string	否	临时访问凭证
`connectionTimeout`	int	否	连接超时时间（毫秒）
`socketTimeout`	int	否	套接字超时时间（毫秒）
`enableVerifySSL`	bool	否	是否校验 SSL 证书，默认 `true`
`autoRecognizeContentType`	bool	否	上传对象时是否按对象后缀自动识别 Content-Type，默认 `true`
`isCustomDomain`	bool	否	是否使用已绑定桶的自定义域名；设为 `true` 时不会把桶名拼到 Endpoint 前
`handler`	callable	否	自定义 Guzzle handler；Swoole/Hyperf 下可传 `Hyperf\Guzzle\CoroutineHandler` 获得连接池复用

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

作者

jsogn - jbanxian@gmail.com

致谢

League\Flysystem - 提供优秀的文件系统抽象
火山引擎 TOS - 提供可靠的对象存储服务

jiangwang / flysystem-tos

Maintainers

Package info

Statistics

Security