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

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

jasonc/flysystem-oss
====================

Flysystem adapter for the Oss storage.

3.0.0(4y ago)0149MITPHPPHP ^7.0 || ^8.0

Since Dec 29Pushed 4y agoCompare

[ Source](https://github.com/cjango/flysystem-oss)[ Packagist](https://packagist.org/packages/jasonc/flysystem-oss)[ RSS](/packages/jasonc-flysystem-oss/feed)WikiDiscussions master Synced 5d ago

READMEChangelog (1)Dependencies (6)Versions (28)Used By (0)

flysystem-oss
==============

[](#flysystem-oss-)

💾 Flysystem adapter for the oss storage.

[![](https://camo.githubusercontent.com/8c128ec0bc47879e9f918a63076fb4168501ed57938c0a8dca1a9aed069e44a4/68747470733a2f2f7472617669732d63692e6f72672f696944657374696e792f666c7973797374656d2d6f73732e7376673f6272616e63683d6d6173746572)](https://github.com/iiDestiny/flysystem-oss)[![](https://camo.githubusercontent.com/62912cb4a11a58a80b0883f19848a7d1eed59542c3649aafb6259f5e395467b8/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3136333530313131392f736869656c64)](https://github.com/iiDestiny/flysystem-oss)[![](https://camo.githubusercontent.com/b536bb67f4b6827f312a239a615ec6faacac4ce3fc32911f3c79592595b66588/68747470733a2f2f706f7365722e707567782e6f72672f696964657374696e792f666c7973797374656d2d6f73732f762f737461626c652e737667)](https://github.com/iiDestiny/flysystem-oss)[![](https://camo.githubusercontent.com/fde5f202ced9ff67d8b50824ea5e8ac0e00d23b573993d51308eef880b14b695/68747470733a2f2f706f7365722e707567782e6f72672f696964657374696e792f666c7973797374656d2d6f73732f762f756e737461626c652e737667)](https://github.com/iiDestiny/flysystem-oss)[![](https://camo.githubusercontent.com/663360b36c0a7f22b1433a67bd752335154cca0c7d76fc017a17b0ad81440b80/68747470733a2f2f706f7365722e707567782e6f72672f696964657374696e792f666c7973797374656d2d6f73732f646f776e6c6f616473)](https://github.com/iiDestiny/flysystem-oss)[![](https://camo.githubusercontent.com/cb1bcb4cebb76a917e3422bee59e37fabdfe320244ac9f4d10d26450b539b42e/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f696944657374696e792f666c7973797374656d2d6f73732f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/iiDestiny/flysystem-oss/?branch=master)[![](https://camo.githubusercontent.com/a8a6219cf0313b681948382bcbcc27a34ae00572d463437bd92ebb1df58647c9/68747470733a2f2f6261646765732e66726170736f66742e636f6d2f6f732f76312f6f70656e2d736f757263652e7376673f763d313033)](https://github.com/iiDestiny/dependency-injection)[![](https://camo.githubusercontent.com/5186a4b337375521ffff80264a7c18f387088c718b7071b9b44fbee3c51f9586/68747470733a2f2f706f7365722e707567782e6f72672f696964657374696e792f666c7973797374656d2d6f73732f6c6963656e7365)](https://github.com/iiDestiny/flysystem-oss)[![996.icu](https://camo.githubusercontent.com/be80b8cb211ceb2263744e99fdb161a40124901906fd7c7f47d6361760dd7e8b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d416e74692532303939362d626c75652e737667)](https://996.icu)

感谢关注「GitHub 热门」公众号，带你了解技术圈内热门新鲜事！
[![](https://camo.githubusercontent.com/402b68eecf0ecdce4dbd6f633a2a4fbd1a7cffb2f636fdb97e80e1191eee724a/68747470733a2f2f63646e2e6c6561726e6b752e636f6d2f75706c6f6164732f696d616765732f3230323031312f30392f343433302f717345437739437467762e6a7067216c61726765)](https://camo.githubusercontent.com/402b68eecf0ecdce4dbd6f633a2a4fbd1a7cffb2f636fdb97e80e1191eee724a/68747470733a2f2f63646e2e6c6561726e6b752e636f6d2f75706c6f6164732f696d616765732f3230323031312f30392f343433302f717345437739437467762e6a7067216c61726765)

扩展包要求
-----

[](#扩展包要求)

- PHP >= 7.0

安装命令
----

[](#安装命令)

```
$ composer require "iidestiny/flysystem-oss" -vvv
```

使用
--

[](#使用)

```
use League\Flysystem\Filesystem;
use Iidestiny\Flysystem\Oss\OssAdapter;
use Iidestiny\Flysystem\Oss\Plugins\FileUrl;

$prefix = ''; // 前缀，非必填
$accessKeyId = 'xxxxxx';
$accessKeySecret = 'xxxxxx';
$endpoint= 'oss.iidestiny.com'; // ssl：https://iidestiny.com
$bucket = 'bucket';
$isCName = true; // 如果 isCname 为 false，endpoint 应配置 oss 提供的域名如：`oss-cn-beijing.aliyuncs.com`，cname 或 cdn 请自行到阿里 oss 后台配置并绑定 bucket

$adapter = new OssAdapter($accessKeyId, $accessKeySecret, $endpoint, $bucket, $isCName, $prefix);

// $adapter->setCdnUrl('https://cdn.iidestiny.com'); // 设置cdn url

$flysystem = new Filesystem($adapter);
```

常用方法
----

[](#常用方法)

```
bool $flysystem->write('file.md', 'contents');

bool $flysystem->write('file.md', 'http://httpbin.org/robots.txt', ['options' => ['xxxxx' => 'application/redirect302']]);

bool $flysystem->writeStream('file.md', fopen('path/to/your/local/file.jpg', 'r'));

bool $flysystem->update('file.md', 'new contents');

bool $flysystem->updateStream('file.md', fopen('path/to/your/local/file.jpg', 'r'));

bool $flysystem->rename('foo.md', 'bar.md');

bool $flysystem->copy('foo.md', 'foo2.md');

bool $flysystem->delete('file.md');

bool $flysystem->has('file.md');

string|false $flysystem->read('file.md');

array $flysystem->listContents();

array $flysystem->getMetadata('file.md');

int $flysystem->getSize('file.md');

string $flysystem->getAdapter()->getUrl('file.md');

string $flysystem->getMimetype('file.md');

int $flysystem->getTimestamp('file.md');
```

插件扩展
----

[](#插件扩展)

```
use Iidestiny\Flysystem\Oss\Plugins\FileUrl;
use Iidestiny\Flysystem\Oss\Plugins\SignUrl;
use Iidestiny\Flysystem\Oss\Plugins\TemporaryUrl;
use Iidestiny\Flysystem\Oss\Plugins\SetBucket;

// 获取 oss 资源访问链接
$flysystem->addPlugin(new FileUrl());

string $flysystem->getUrl('file.md');

// url 访问有效期 & 图片处理「$timeout 为多少秒过期」
$flysystem->addPlugin(new SignUrl());

// 默认GET
string $flysystem->signUrl('file.md', $timeout, ['x-oss-process' => 'image/circle,r_100']);

// PUT方式
string $flysystem->signUrl('file.md', $timeout, ['x-oss-process' => 'image/circle,r_100'],'PUT');

 // url 访问有效期「$expiration 为未来时间 2019-05-05 17:50:32」
$flysystem->addPlugin(new TemporaryUrl());

// 默认GET
string $flysystem->getTemporaryUrl('file.md', $expiration);

// PUT方式
string $flysystem->getTemporaryUrl('file.md', $expiration,[],'PUT');

// 多个bucket切换
$flysystem->addPlugin(new SetBucket());
$flysystem->bucket('test')->has('file.md');
```

获取官方完整 OSS 处理能力
---------------

[](#获取官方完整-oss-处理能力)

阿里官方 SDK 可能处理了更多的事情，如果你想获取完整的功能可通过此插件获取， 然后你将拥有完整的 oss 处理能力

```
use Iidestiny\Flysystem\Oss\Plugins\Kernel;

$flysystem->addPlugin(new Kernel());
$kernel = $flysystem->kernel();

// 例如：防盗链功能
$refererConfig = new RefererConfig();
// 设置允许空Referer。
$refererConfig->setAllowEmptyReferer(true);
// 添加Referer白名单。Referer参数支持通配符星号（*）和问号（？）。
$refererConfig->addReferer("www.aliiyun.com");
$refererConfig->addReferer("www.aliiyuncs.com");

$kernel->putBucketReferer($bucket, $refererConfig);
```

> 更多功能请查看官方 SDK 手册：[https://help.aliyun.com/document\_detail/32100.html?spm=a2c4g.11186623.6.1055.66b64a49hkcTHv](https://help.aliyun.com/document_detail/32100.html?spm=a2c4g.11186623.6.1055.66b64a49hkcTHv)

前端 web 直传配置
-----------

[](#前端-web-直传配置)

oss 直传有三种方式，当前扩展包使用的是最完整的 [服务端签名直传并设置上传回调](https://help.aliyun.com/document_detail/31927.html?spm=a2c4g.11186623.2.10.5602668eApjlz3#concept-qp2-g4y-5db) 方式，**扩展包只生成前端页面上传所需的签名参数**，前端上传实现可参考 [官方文档中的实例](https://help.aliyun.com/document_detail/31927.html?spm=a2c4g.11186623.2.10.5602668eApjlz3#concept-qp2-g4y-5db) 或自行搜索

```
use Iidestiny\Flysystem\Oss\Plugins\SignatureConfig;

$flysystem->addPlugin(new SignatureConfig());

/**
 * 1. 前缀如：'images/'
 * 2. 回调服务器 url
 * 3. 回调自定义参数，oss 回传应用服务器时会带上
 * 4. 当前直传配置链接有效期
 * 5. 文件大小限制
 * 6. 回调系统参数, 默认值: Iidestiny\Flysystem\Oss\OssAdapter::SYSTEM_FIELD
 */
object $flysystem->signatureConfig($prefix = '/', $callBackUrl = '', $customData = [], $expire = 30, $maxSize = 1024 * 1024 * 2, $systemData = ['etag' => '${etag}', 'filename' => '${object}']);
```

直传回调验签
------

[](#直传回调验签)

当设置了直传回调后，可以通过验签插件，验证并获取 oss 传回的数据 [文档](https://help.aliyun.com/document_detail/91771.html?spm=a2c4g.11186623.2.15.7ee07eaeexR7Y1#title-9t0-sge-pfr)

注意事项：

- 如果没有 Authorization 头信息导致验签失败需要先在 apache 或者 nginx 中设置 rewrite
- 以 apache 为例，修改 httpd.conf 在 DirectoryIndex index.php 这行下面增加「RewriteEngine On」「RewriteRule .\* - \[env=HTTP\_AUTHORIZATION:%{HTTP:Authorization},last\]」

```
use Iidestiny\Flysystem\Oss\Plugins\Verify;

$flysystem->addPlugin(new Verify());

list($verify, $data) = $flysystem->verify();
// [$verify, $data] = $flysystem->verify(); // php 7.1 +

if (!$verify) {
    // 验证失败处理，此时 $data 为验签失败提示信息
}

// 注意一定要返回 json 格式的字符串，因为 oss 服务器只接收 json 格式，否则给前端报 CallbackFailed
header("Content-Type: application/json");
echo  json_encode($data);
```

直传回调验签后返回给前端的数据「包括自定义参数」，例如

```
{
    "bucket": "your-bucket",
    "etag": "D8E8FCA2DC0F896FD7CB4CB0031BA249",
    "filename": "user/15854050909488182.png",
    "size": "56039",
    "mimeType": "image/png",
    "height": "473",
    "width": "470",
    "format": "png",
    "custom_name": "zhangsan",
    "custom_age": "24"
}
```

> 这其实要看你回调通知方法具体怎么返回，如果直接按照文档给的方法返回是这个样子

前端直传组件分享「vue + element」
-----------------------

[](#前端直传组件分享vue--element)

```

import { getOssPolicy } from '@/api/oss' // 这里就是获取直传配置接口

export default {
  name: 'Upload',
  props: {
    url: {
      type: String,
      default: null
    }
  },
  data() {
    return {
      uploadUrl: '', // 上传提交地址
      data: {}, // 上传提交额外数据
      dialogImageUrl: '', // 预览图片
      files: [] // 上传的文件
    }
  },
  computed: {},
  created() {
    this.dialogImageUrl = this.url
  },
  methods: {
    handleChange(file, fileList) {
      console.log(file, fileList)
    },
    // 上传之前处理动作
    async handleBeforeUpload(file) {
      const fileName = this.makeRandomName(file.name)
      try {
        const response = await getOssPolicy()

        this.uploadUrl = response.host

        // 组装自定义参数
        if (Object.keys(response['callback-var']).length) {
          for (const [key, value] of Object.entries(response['callback-var'])) {
            this.data[key] = value
          }
        }

        this.data.policy = response.policy
        this.data.OSSAccessKeyId = response.accessid
        this.data.signature = response.signature
        this.data.host = response.host
        this.data.callback = response.callback
        this.data.key = response.dir + fileName
      } catch (error) {
        this.$message.error('获取上传配置失败')
        console.log(error)
      }
    },
    // 文件上传成功处理
    handleSucess(response, file, fileList) {
      const fileUrl = this.uploadUrl + this.data.key
      this.dialogImageUrl = fileUrl
      this.$emit('update:url', fileUrl)
      this.files.push({
        name: this.data.key,
        url: fileUrl
      })
    },
    // 上传失败处理
    handleError() {
      this.$message.error('上传失败')
    },
    // 随机名称
    makeRandomName(name) {
      const randomStr = Math.random().toString().substr(2, 4)
      const suffix = name.substr(name.lastIndexOf('.'))
      return Date.now() + randomStr + suffix
    }
  }

}

.avatar-uploader .el-upload {
    border: 1px dashed #d9d9d9;
    border-radius: 6px;
    cursor: pointer;
    position: relative;
    overflow: hidden;
  }
  .avatar-uploader .el-upload:hover {
    border-color: #409EFF;
  }
  .avatar-uploader-icon {
    font-size: 28px;
    color: #8c939d;
    width: 150px;
    height: 150px;
    line-height: 150px;
    text-align: center;
  }
  .avatar {
    width: 150px;
    height: 150px;
    display: block;
  }

```

Laravel 适配包
-----------

[](#laravel-适配包)

- Laravel 5：[iidestiny/laravel-filesystem-oss](https://github.com/iiDestiny/laravel-filesystem-oss)

参考
--

[](#参考)

- [overtrue/flysystem-qiniu](https://github.com/overtrue/flysystem-qiniu)

License
-------

[](#license)

[![LICENSE](https://camo.githubusercontent.com/be80b8cb211ceb2263744e99fdb161a40124901906fd7c7f47d6361760dd7e8b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d416e74692532303939362d626c75652e737667)](https://github.com/996icu/996.ICU/blob/master/LICENSE)

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 83.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

Every ~42 days

Recently: every ~76 days

Total

25

Last Release

1690d ago

Major Versions

1.4.0 → 2.02020-03-28

2.7 → 3.0.02021-09-30

PHP version history (2 changes)1.0PHP ^7.0

2.4PHP ^7.0 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/b057654b5ef7e0c8fa3a6808cf812053ac9a7ce2bbd637c8f8889171db8572c1?d=identicon)[jasonencode](/maintainers/jasonencode)

---

Top Contributors

[![iiDestiny](https://avatars.githubusercontent.com/u/17637481?v=4)](https://github.com/iiDestiny "iiDestiny (128 commits)")[![miaotaizi](https://avatars.githubusercontent.com/u/6868360?v=4)](https://github.com/miaotaizi "miaotaizi (10 commits)")[![iwisen](https://avatars.githubusercontent.com/u/35598665?v=4)](https://github.com/iwisen "iwisen (4 commits)")[![bddbnet](https://avatars.githubusercontent.com/u/11495285?v=4)](https://github.com/bddbnet "bddbnet (3 commits)")[![liujiajia](https://avatars.githubusercontent.com/u/620642?v=4)](https://github.com/liujiajia "liujiajia (2 commits)")[![jxlwqq](https://avatars.githubusercontent.com/u/2421068?v=4)](https://github.com/jxlwqq "jxlwqq (1 commits)")[![smartymoon](https://avatars.githubusercontent.com/u/12489528?v=4)](https://github.com/smartymoon "smartymoon (1 commits)")[![zxdstyle](https://avatars.githubusercontent.com/u/38398954?v=4)](https://github.com/zxdstyle "zxdstyle (1 commits)")[![fenyoyo](https://avatars.githubusercontent.com/u/133726969?v=4)](https://github.com/fenyoyo "fenyoyo (1 commits)")[![ihipop](https://avatars.githubusercontent.com/u/423077?v=4)](https://github.com/ihipop "ihipop (1 commits)")[![jasonencode](https://avatars.githubusercontent.com/u/2210843?v=4)](https://github.com/jasonencode "jasonencode (1 commits)")[![JimChenWYU](https://avatars.githubusercontent.com/u/12371374?v=4)](https://github.com/JimChenWYU "JimChenWYU (1 commits)")

---

Tags

laravelossalioss

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[iidestiny/flysystem-oss

Flysystem adapter for the Oss storage.

95607.5k26](/packages/iidestiny-flysystem-oss)[jacobcyl/ali-oss-storage

aliyun oss filesystem storage for laravel 5+

523566.2k7](/packages/jacobcyl-ali-oss-storage)[yangyifan/upload

上传 SDK for Laravel

12422.6k3](/packages/yangyifan-upload)[luoyy/ali-oss-storage

aliyun oss filesystem storage for laravel 9+

1529.9k1](/packages/luoyy-ali-oss-storage)[aobozhang/aliyun-oss-adapter

Use Aliyun oss as Storage for Laravel 5.0+

141.0k](/packages/aobozhang-aliyun-oss-adapter)

PHPackages © 2026

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