PHPackages                             vergil-lai/oss-flysystem - 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. vergil-lai/oss-flysystem

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

vergil-lai/oss-flysystem
========================

Flysystem adapter for Alibaba Cloud OSS using the OSS PHP SDK v2.

v1.0.0(1mo ago)107↓33.3%1MITPHPPHP ^8.2

Since Jul 18Pushed 1mo agoCompare

[ Source](https://github.com/vergil-lai/oss-flysystem)[ Packagist](https://packagist.org/packages/vergil-lai/oss-flysystem)[ RSS](/packages/vergil-lai-oss-flysystem/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (1)Dependencies (7)Versions (2)Used By (1)

OSS Flysystem
=============

[](#oss-flysystem)

基于 [Alibaba Cloud OSS PHP SDK V2](https://github.com/aliyun/alibabacloud-oss-php-sdk-v2) 的 Flysystem 3 适配器。

要求
--

[](#要求)

- PHP 8.2+
- 阿里云 OSS bucket 的访问凭证与 region

OSS SDK V2 默认使用 V4 签名，因此必须配置 bucket 所在的 `region`。

安装
--

[](#安装)

```
composer require vergil-lai/oss-flysystem
```

使用
--

[](#使用)

本包直接接收 OSS SDK V2 原生 `Client`，不提供第二套客户端或配置格式：

```
use AlibabaCloud\Oss\V2\Client;
use AlibabaCloud\Oss\V2\Config as OssConfig;
use AlibabaCloud\Oss\V2\Credentials\StaticCredentialsProvider;
use League\Flysystem\Filesystem;
use VergilLai\OssFlysystem\OssFlysystemAdapter;

$config = OssConfig::loadDefault();
$config->setRegion(getenv('OSS_REGION') ?: 'cn-hangzhou');
$config->setCredentialsProvider(new StaticCredentialsProvider(
    (string) getenv('OSS_ACCESS_KEY_ID'),
    (string) getenv('OSS_ACCESS_KEY_SECRET'),
    getenv('OSS_SESSION_TOKEN') ?: null,
));

if ($endpoint = getenv('OSS_ENDPOINT')) {
    $config->setEndpoint($endpoint);
}

$client = new Client($config);
$adapter = new OssFlysystemAdapter(
    $client,
    (string) getenv('OSS_BUCKET'),
    baseUrl: getenv('OSS_URL') ?: null,
);
$filesystem = new Filesystem($adapter);

$filesystem->write('docs/readme.txt', 'Hello OSS');
$contents = $filesystem->read('docs/readme.txt');
```

`endpoint` 可选；未配置时由 SDK 根据 `region` 选择 endpoint。SDK V2 默认使用 V4 签名，如需 V1 可调用 `$config->setSignatureVersion('v1')`。代理、超时、重试和 endpoint 等参数均直接使用 SDK `Config` 的设置方法。

自定义凭证提供器和重试器
------------

[](#自定义凭证提供器和重试器)

凭证提供器和重试器直接设置到 SDK `Config`：

```
use AlibabaCloud\Oss\V2\Credentials\EnvironmentVariableCredentialsProvider;
use AlibabaCloud\Oss\V2\Retry\StandardRetryer;

$config->setCredentialsProvider(new EnvironmentVariableCredentialsProvider());
$config->setRetryer(new StandardRetryer(maxAttempts: 5));
```

如果没有设置 retryer，SDK 会使用默认的 `StandardRetryer`。仅需调整最大重试次数时，可调用 `$config->setRetryMaxAttempts(5)`。

Root 与公开 URL
------------

[](#root-与公开-url)

适配器的第三个参数是对象 key 的 `root` 前缀，第四个参数是公开 URL 的 `baseUrl`：

```
$adapter = new OssFlysystemAdapter(
    $client,
    (string) getenv('OSS_BUCKET'),
    'uploads',
    'https://cdn.example.com',
);
```

上例中 `avatars/me.png` 会存储为 `uploads/avatars/me.png`，`$adapter->getUrl('avatars/me.png')` 会返回以 `https://cdn.example.com/uploads/` 开头的地址。

SDK `Client` 不公开其内部 endpoint 配置，因此本包不会从 Client 反向推断公开 URL。需要调用 `publicUrl()` 或 `getUrl()` 时必须传入 `baseUrl`；临时 URL 由 SDK `presign()` 生成，不受此限制。

支持的操作
-----

[](#支持的操作)

- 写入、读取及流式读写
- 文件是否存在、文件大小、MIME 类型、最后修改时间和可见性
- 列出内容、复制、移动、删除文件和目录
- `checksum`（使用 OSS ETag）
- 公开 URL、临时 GET URL 与临时 PUT 上传 URL

临时 URL 使用 SDK `Config` 设置的签名版本生成，默认为 OSS V4。除了 Flysystem 的 `$filesystem->temporaryUrl()` 外，如需临时上传 URL，可直接使用适配器：

```
$upload = $adapter->temporaryUploadUrl(
    'photo.jpg',
    new DateTimeImmutable('+10 minutes'),
    ['mimetype' => 'image/jpeg'],
);

// 使用 $upload['url'] 和 $upload['headers'] 发起 PUT 上传。
```

写入和临时上传支持 `visibility`、`mimetype`、`cache_control`、`content_disposition`、`content_encoding`、`metadata`、`forbid_overwrite` 与 `storage_class` 等常用选项。

Laravel
-------

[](#laravel)

Laravel 项目请安装 [`vergil-lai/laravel-oss-filesystem`](https://github.com/vergil-lai/laravel-oss-filesystem)。它会通过 Composer 自动安装本包，并提供 `Storage::disk('oss')` 集成。

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance90

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

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

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7381568?v=4)[vergil](/maintainers/vergil)[@Vergil](https://github.com/Vergil)

---

Top Contributors

[![vergil-lai](https://avatars.githubusercontent.com/u/2268937?v=4)](https://github.com/vergil-lai "vergil-lai (10 commits)")

---

Tags

filesystemFlysystemaliyunoss

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/vergil-lai-oss-flysystem/health.svg)

```
[![Health](https://phpackages.com/badges/vergil-lai-oss-flysystem/health.svg)](https://phpackages.com/packages/vergil-lai-oss-flysystem)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.4k567.5M2.9k](/packages/aws-aws-sdk-php)[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.

605.9M718](/packages/shopware-core)[tempest/framework

The PHP framework that gets out of your way.

2.3k42.4k21](/packages/tempest-framework)[google/cloud

Google Cloud Client Library

1.2k17.1M58](/packages/google-cloud)[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.7k302.9M1.2k](/packages/league-flysystem-aws-s3-v3)

PHPackages © 2026

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