PHPackages                             larva/flysystem-tos - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. larva/flysystem-tos

ActiveLibrary[File & Storage](/categories/file-storage)

larva/flysystem-tos
===================

Flysystem adapter for the volc engine TOS storage.

1.1.1(1w ago)09121MITPHP

Since Jun 23Pushed 1w agoCompare

[ Source](https://github.com/larva-cool/flysystem-tos)[ Packagist](https://packagist.org/packages/larva/flysystem-tos)[ RSS](/packages/larva-flysystem-tos/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (12)Versions (13)Used By (1)

flysystem-tos
=============

[](#flysystem-tos)

 [![Stable Version](https://camo.githubusercontent.com/fc8e4cdb8760ea37b8267e4bbda8b51604a0323eb173c3b3e8a4b143cc046424/68747470733a2f2f706f7365722e707567782e6f72672f6c617276612f666c7973797374656d2d746f732f762f737461626c65)](https://packagist.org/packages/larva/flysystem-tos) [![Total Downloads](https://camo.githubusercontent.com/d911773ed159892c25d9f169793d5d10fa2d3c77356e16684f49dc6804b47e53/68747470733a2f2f706f7365722e707567782e6f72672f6c617276612f666c7973797374656d2d746f732f646f776e6c6f616473)](https://packagist.org/packages/larva/flysystem-tos) [![License](https://camo.githubusercontent.com/bdb86b8447ee5f5a52a92a556fa670f639ca6df3d859a20baa5928cef9270e37/68747470733a2f2f706f7365722e707567782e6f72672f6c617276612f666c7973797374656d2d746f732f6c6963656e7365)](https://packagist.org/packages/larva/flysystem-tos)

这是火山引擎 TOS（Tinder Object Storage）对象存储的 [Flysystem](https://flysystem.thephpleague.com/) 适配器，支持 Flysystem v2/v3。

环境要求
----

[](#环境要求)

- PHP >= 8.0
- Composer 2.0+
- Flysystem v2 或 v3
- 火山引擎 TOS PHP SDK v2.1+

安装
--

[](#安装)

```
composer require larva/flysystem-tos -vv
```

基础用法
----

[](#基础用法)

### 1. 创建 TOS 客户端

[](#1-创建-tos-客户端)

```
use Tos\TosClient;

$client = new TosClient([
    'region' => 'cn-beijing',
    'endpoint' => 'tos-cn-beijing.volces.com',
    'ak' => 'your-access-key',
    'sk' => 'your-secret-key',
]);
```

### 2. 创建适配器

[](#2-创建适配器)

```
use Larva\Flysystem\Tos\TOSAdapter;
use Larva\Flysystem\Tos\PortableVisibilityConverter;

$adapter = new TOSAdapter(
    client: $client,
    bucket: 'your-bucket-name',
    prefix: '',                              // 可选，存储路径前缀
    visibility: new PortableVisibilityConverter(), // 可选，可见性转换器
    mimeTypeDetector: null,                 // 可选，MIME 类型检测器
    options: []                             // 可选，额外选项
);
```

### 3. 配合 Filesystem 使用

[](#3-配合-filesystem-使用)

```
use League\Flysystem\Filesystem;

$filesystem = new Filesystem($adapter);

// 写入文件
$filesystem->write('path/to/file.txt', 'file contents');

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

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

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

// 列出目录内容
foreach ($filesystem->listContents('path/to/dir') as $item) {
    echo $item->path() . PHP_EOL;
}
```

可见性控制
-----

[](#可见性控制)

适配器通过 `VisibilityConverter` 接口将 Flysystem 的可见性（`public` / `private`）映射为 TOS 的 ACL：

Flysystem 可见性TOS ACL`Visibility::PUBLIC``public-read``Visibility::PRIVATE``private`默认使用 `PortableVisibilityConverter`，你也可以实现 `VisibilityConverter` 接口自定义映射逻辑：

```
use Larva\Flysystem\Tos\VisibilityConverter;
use League\Flysystem\Visibility;

class CustomVisibilityConverter implements VisibilityConverter
{
    public function visibilityToAcl(string $visibility): string
    {
        return $visibility === Visibility::PUBLIC ? 'public-read' : 'private';
    }

    public function aclToVisibility(string $acl): string
    {
        return $acl === 'public-read' ? Visibility::PUBLIC : Visibility::PRIVATE;
    }

    public function defaultForDirectories(): string
    {
        return Visibility::PUBLIC;
    }
}
```

支持的方法
-----

[](#支持的方法)

方法说明`write($path, $contents, $config)`写入文件`writeStream($path, $stream, $config)`以流的方式写入文件`read($path)`读取文件内容`readStream($path)`以流的方式读取文件`fileExists($path)`判断文件是否存在`directoryExists($path)`判断目录是否存在`delete($path)`删除文件`deleteDirectory($path)`删除目录`createDirectory($path, $config)`创建目录`setVisibility($path, $visibility)`设置文件可见性`visibility($path)`获取文件可见性`mimeType($path)`获取文件 MIME 类型`lastModified($path)`获取文件最后修改时间`fileSize($path)`获取文件大小`listContents($path, $deep)`列出目录内容`move($source, $destination, $config)`移动文件`copy($source, $destination, $config)`复制文件Laravel 集成
----------

[](#laravel-集成)

在 Laravel 项目中，可以通过自定义 Filesystem 驱动的方式集成：

```
// AppServiceProvider::boot()
use Illuminate\Support\Facades\Storage;
use Larva\Flysystem\Tos\TOSAdapter;
use League\Flysystem\Filesystem;

Storage::extend('tos', function ($app, $config) {
    $client = new \Tos\TosClient([
        'region' => $config['region'],
        'endpoint' => $config['endpoint'],
        'ak' => $config['ak'],
        'sk' => $config['sk'],
    ]);

    $adapter = new TOSAdapter($client, $config['bucket'], $config['prefix'] ?? '');

    return new Filesystem($adapter);
});
```

在 `config/filesystems.php` 中添加磁盘配置：

```
'tos' => [
    'driver' => 'tos',
    'region' => env('TOS_REGION', 'cn-beijing'),
    'endpoint' => env('TOS_ENDPOINT', 'tos-cn-beijing.volces.com'),
    'ak' => env('TOS_AK'),
    'sk' => env('TOS_SK'),
    'bucket' => env('TOS_BUCKET'),
    'prefix' => env('TOS_PREFIX', ''),
],
```

然后在 `.env` 中配置相应的环境变量：

```
TOS_REGION=cn-beijing
TOS_ENDPOINT=tos-cn-beijing.volces.com
TOS_AK=your-access-key
TOS_SK=your-secret-key
TOS_BUCKET=your-bucket-name
TOS_PREFIX=
```

使用方式：

```
Storage::disk('tos')->put('file.txt', 'contents');
$contents = Storage::disk('tos')->get('file.txt');
```

获取客户端
-----

[](#获取客户端)

如需直接操作 TOS SDK，可以获取底层客户端：

```
$client = $adapter->getClient();
$bucket = $adapter->getBucket();
```

贡献
--

[](#贡献)

欢迎提交 Issue 和 Pull Request。

License
-------

[](#license)

[MIT](LICENSE)

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance98

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~37 days

Total

12

Last Release

9d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/534cdb651e8c806590fa945c6b5a18f361613848e890db1349f4a9fbcae1a650?d=identicon)[xutongle](/maintainers/xutongle)

---

Top Contributors

[![xutongle](https://avatars.githubusercontent.com/u/46956076?v=4)](https://github.com/xutongle "xutongle (13 commits)")

---

Tags

flysystemflysystem-adaptertosvolcengine

###  Code Quality

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/larva-flysystem-tos/health.svg)

```
[![Health](https://phpackages.com/badges/larva-flysystem-tos/health.svg)](https://phpackages.com/packages/larva-flysystem-tos)
```

###  Alternatives

[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.7k293.8M1.2k](/packages/league-flysystem-aws-s3-v3)[tempest/framework

The PHP framework that gets out of your way.

2.3k37.6k21](/packages/tempest-framework)[league/flysystem

File storage abstraction for PHP

13.6k694.3M2.7k](/packages/league-flysystem)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.8M672](/packages/shopware-core)[unisharp/laravel-filemanager

A file upload/editor intended for use with Laravel 5 to 10 and CKEditor / TinyMCE

2.2k3.6M90](/packages/unisharp-laravel-filemanager)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)