PHPackages larva/flysystem-kodo - 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-kodo ActiveLibrary[File & Storage](/categories/file-storage) larva/flysystem-kodo ==================== This is a Flysystem adapter for the Qiniu kodo. 1.0.0(3w ago)051MITPHPPHP ^8.2 Since Jul 24Pushed 1w agoCompare [ Source](https://github.com/larva-cool/flysystem-kodo)[ Packagist](https://packagist.org/packages/larva/flysystem-kodo)[ RSS](/packages/larva-flysystem-kodo/feed)WikiDiscussions master Synced 1w ago READMEChangelog (1)Dependencies (4)Versions (2)Used By (1) flysystem-kodo ============== [](#flysystem-kodo) [![Stable Version](https://camo.githubusercontent.com/76cb27ffe1888451ab6ffd9f35048cb20f6f298864c80281fa7ae519e1738dbf/68747470733a2f2f706f7365722e707567782e6f72672f6c617276612f666c7973797374656d2d6b6f646f2f762f737461626c65)](https://packagist.org/packages/larva/flysystem-kodo) [![Total Downloads](https://camo.githubusercontent.com/ebd12cf17a69651983b93acc9ea395ce8a0c0120469e2b43ea690755c16eb7d2/68747470733a2f2f706f7365722e707567782e6f72672f6c617276612f666c7973797374656d2d6b6f646f2f646f776e6c6f616473)](https://packagist.org/packages/larva/flysystem-kodo) [![License](https://camo.githubusercontent.com/c6ab96e4668caa7769c99098b6b427a85322c37bfe0e2e9f5a3f45cbe96f297a/68747470733a2f2f706f7365722e707567782e6f72672f6c617276612f666c7973797374656d2d6b6f646f2f6c6963656e7365)](https://packagist.org/packages/larva/flysystem-kodo) 这是七牛云 Kodo（对象存储）的 [Flysystem](https://flysystem.thephpleague.com/) 适配器，支持 Flysystem v2/v3。 环境要求 ---- [](#环境要求) - PHP >= 8.2 - Composer 2.0+ - Flysystem v2 或 v3 - 七牛云 PHP SDK v7.14+ 安装 -- [](#安装) ``` composer require larva/flysystem-kodo -vv ``` 基础用法 ---- [](#基础用法) ### 1. 创建七牛 Auth 实例 [](#1-创建七牛-auth-实例) ``` use Qiniu\Auth; $auth = new Auth('your-access-key', 'your-secret-key'); ``` ### 2. 创建适配器 [](#2-创建适配器) ``` use Larva\Flysystem\Qiniu\QiniuKodoAdapter; use Larva\Flysystem\Qiniu\PortableVisibilityConverter; $adapter = new QiniuKodoAdapter( auth: $auth, bucket: 'your-bucket-name', domain: 'https://your-domain.com', // 绑定的域名（用于下载文件） 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`）映射为七牛云的访问控制： Flysystem 可见性七牛云 ACL`Visibility::PUBLIC``public-read``Visibility::PRIVATE``private`> **注意**：七牛云的可见性为 bucket 级别设置，非单文件级别。调用 `setVisibility` 会修改整个 bucket 的访问权限。 默认使用 `PortableVisibilityConverter`，你也可以实现 `VisibilityConverter` 接口自定义映射逻辑： ``` use Larva\Flysystem\Qiniu\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; } } ``` 上传回调 ---- [](#上传回调) 上传文件时支持七牛云的回调通知配置： ``` use League\Flysystem\Config; $filesystem->write('path/to/file.txt', 'contents', new Config([ 'callbackUrl' => 'https://example.com/callback', 'callbackBody' => '{"key":"$(key)","hash":"$(etag)","fsize":$(fsize)}', 'callbackBodyType' => 'application/json', ])); ``` 支持的方法 ----- [](#支持的方法) 方法说明`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)`设置 bucket 可见性`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\Qiniu\QiniuKodoAdapter; use League\Flysystem\Filesystem; use Qiniu\Auth; Storage::extend('qiniu', function ($app, $config) { $auth = new Auth($config['access_key'], $config['secret_key']); $adapter = new QiniuKodoAdapter( auth: $auth, bucket: $config['bucket'], domain: $config['domain'], prefix: $config['prefix'] ?? '' ); return new Filesystem($adapter); }); ``` 在 `config/filesystems.php` 中添加磁盘配置： ``` 'qiniu' => [ 'driver' => 'qiniu', 'access_key' => env('QINIU_ACCESS_KEY'), 'secret_key' => env('QINIU_SECRET_KEY'), 'bucket' => env('QINIU_BUCKET'), 'domain' => env('QINIU_DOMAIN'), 'prefix' => env('QINIU_PREFIX', ''), ], ``` 然后在 `.env` 中配置相应的环境变量： ``` QINIU_ACCESS_KEY=your-access-key QINIU_SECRET_KEY=your-secret-key QINIU_BUCKET=your-bucket-name QINIU_DOMAIN=https://your-domain.com QINIU_PREFIX= ``` 使用方式： ``` Storage::disk('qiniu')->put('file.txt', 'contents'); $contents = Storage::disk('qiniu')->get('file.txt'); ``` 获取底层 SDK 实例 ----------- [](#获取底层-sdk-实例) 如需直接操作七牛云 SDK，可以获取底层实例： ``` // 获取 Auth 实例 $auth = $adapter->getAuth(); // 获取 BucketManager 实例 $bucketManager = $adapter->getBucketManager(); // 获取 UploadManager 实例 $uploadManager = $adapter->getUploadManager(); // 获取 bucket 名称 $bucket = $adapter->getBucket(); // 获取绑定域名 $domain = $adapter->getDomain(); ``` 贡献 -- [](#贡献) 欢迎提交 Issue 和 Pull Request。 License ------- [](#license) [MIT](LICENSE) ### Health Score 41 — FairBetter than 87% of packages Maintenance97 Actively maintained with recent releases Popularity5 Limited adoption so far Community12 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 57.1% 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 Unknown Total 1 Last Release 23d 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 (4 commits)")[![xutl](https://avatars.githubusercontent.com/u/20939388?v=4)](https://github.com/xutl "xutl (3 commits)") --- Tags FlysystemqiniuLarvakodo ### Code Quality Code StylePHP CS Fixer ### Embed Badge ![Health badge](/badges/larva-flysystem-kodo/health.svg) ``` [![Health](https://phpackages.com/badges/larva-flysystem-kodo/health.svg)](https://phpackages.com/packages/larva-flysystem-kodo) ``` ### 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)[league/flysystem-sftp-v3 SFTP filesystem adapter for Flysystem. 6136.6M182](/packages/league-flysystem-sftp-v3) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)