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

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

lonelywalkersource/flysystem-oss
================================

Flysystem adapter for Alibaba Cloud OSS storage.

v1.0.0(2w ago)02↓100%1MITPHPPHP ^8.2

Since May 26Pushed 2w agoCompare

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

READMEChangelogDependencies (7)Versions (2)Used By (1)

lonelywalkersource/flysystem-oss
================================

[](#lonelywalkersourceflysystem-oss)

> [中文文档](README-ZH.md)

Flysystem adapter for Alibaba Cloud OSS (Object Storage Service).

### Requirements

[](#requirements)

- PHP ^8.2
- league/flysystem ^3.0
- aliyuncs/oss-sdk-php ^2.0

### Installation

[](#installation)

```
composer require lonelywalkersource/flysystem-oss
```

### Usage

[](#usage)

#### Configuration Reference

[](#configuration-reference)

All available options for `OssConfig::fromArray()`:

```
use Lonelywalksource\Flysystem\Oss\Config\OssConfig;
use Lonelywalksource\Flysystem\Oss\OssAdapter;

$config = OssConfig::fromArray([
    // ── Required ─────────────────────────────────────────

    // Alibaba Cloud AccessKey ID (alias: 'key')
    'access_key'     => 'your-access-key',

    // Alibaba Cloud AccessKey Secret (alias: 'secret')
    'secret_key'     => 'your-secret-key',

    // OSS endpoint, e.g. oss-cn-hangzhou.aliyuncs.com
    'endpoint'       => 'oss-cn-hangzhou.aliyuncs.com',

    // Bucket name
    'bucket'         => 'your-bucket',

    // ── Optional ─────────────────────────────────────────

    // Region (e.g. cn-hangzhou) — required for V4 signature and post policy
    'region'         => 'cn-hangzhou',

    // Whether endpoint is a custom domain (CNAME). Default: false
    'isCName'        => false,

    // STS security token (for temporary credentials)
    'security_token' => null,

    // CDN domain — when set, getUrl() returns CDN URLs instead of OSS URLs
    'domain'         => 'https://cdn.example.com',

    // Path prefix for all OSS object keys. Default: ''
    'path_prefix'    => '',

    // Multi-bucket configuration — see "Multi-Bucket" section below
    'buckets'        => [],

    // Signature version for OSS client, e.g. OssClient::OSS_SIGNATURE_VERSION_V4
    'signature_version' => null,

    // Connection timeout in seconds
    'timeout'        => null,

    // ── Flysystem Options ────────────────────────────────

    // Whether to throw exceptions. Default: true
    'throw'          => true,

    // ── OssClient Extra Options ──────────────────────────
    // Any key not listed above is passed directly to the OssClient constructor.
    // Valid OssClient options include: request_proxy, forcePathStyle, cloudBoxId,
    // strictObjectName, checkObjectEncoding, filePathCompatible.
    // Example:
    // 'request_proxy' => 'http://proxy.example.com:8080',
]);

$adapter = new OssAdapter($config);
```

#### Basic Usage

[](#basic-usage)

```
$adapter = new OssAdapter($config);
$adapter->write('path/to/file.txt', 'Hello OSS', new \League\Flysystem\Config());
```

#### With Custom OssClient

[](#with-custom-ossclient)

```
$client = new \OSS\OssClient([...]);
$adapter = new OssAdapter($config, $client);
```

#### Multi-Bucket

[](#multi-bucket)

```
$config = OssConfig::fromArray([
    'access_key' => 'your-access-key',
    'secret_key' => 'your-secret-key',
    'endpoint'   => 'oss-cn-hangzhou.aliyuncs.com',
    'bucket'     => 'default-bucket',
    'buckets'    => [
        'images' => [
            'bucket'   => 'images-bucket',
            'endpoint' => 'oss-cn-beijing.aliyuncs.com',
        ],
    ],
]);

$adapter = new OssAdapter($config);
$adapter->write('file.txt', 'goes to default bucket', new \League\Flysystem\Config());

$imagesAdapter = $adapter->bucket('images');
$imagesAdapter->write('photo.jpg', 'goes to images bucket', new \League\Flysystem\Config());
```

#### CDN Domain

[](#cdn-domain)

```
$adapter->setDomain('https://cdn.example.com');
echo $adapter->getUrl('file.txt'); // https://cdn.example.com/file.txt
```

#### Generate Post Policy (for direct upload)

[](#generate-post-policy-for-direct-upload)

```
$result = $adapter->generatePostPolicy([
    'expire' => 1800,
    'prefix' => 'uploads/',
]);
// $result['policy_token_json'] contains form fields for direct OSS upload
```

#### Get Temporary URL

[](#get-temporary-url)

```
$url = $adapter->getTemporaryUrl('file.txt', 3600); // 1 hour
```

#### Verify Callback

[](#verify-callback)

```
$result = $adapter->verifyCallback(
    authorizationBase64: $_SERVER['HTTP_AUTHORIZATION'] ?? '',
    pubKeyUrlBase64: $_SERVER['HTTP_X_OSS_PUB_KEY_URL'] ?? '',
    path: $_SERVER['REQUEST_URI'] ?? '',
    body: file_get_contents('php://input'),
);
[$ok, $data] = $result;
```

#### Using CallbackSigner (PSR-18)

[](#using-callbacksigner-psr-18)

```
use Lonelywalksource\Flysystem\Oss\Signer\CallbackSigner;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;

$signer = new CallbackSigner($httpClient, $requestFactory);
$result = $signer->verify($authorization, $pubKeyUrl, $path, $body);
```

### License

[](#license)

MIT

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance97

Actively maintained with recent releases

Popularity3

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

15d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/81b4ab1385a9e89363131b15f1390935141bf18afc34db5740be66391ace6bfc?d=identicon)[walkerdistance](/maintainers/walkerdistance)

---

Top Contributors

[![lonelywalkersource](https://avatars.githubusercontent.com/u/69964662?v=4)](https://github.com/lonelywalkersource "lonelywalkersource (1 commits)")

---

Tags

Flysystemaliyunossaliossobject-storage

###  Code Quality

TestsPest

### Embed Badge

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

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

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k11](/packages/tempest-framework)[iidestiny/flysystem-oss

Flysystem adapter for the Oss storage.

96628.8k27](/packages/iidestiny-flysystem-oss)[luoyy/ali-oss-storage

aliyun oss filesystem storage for laravel 10+

1530.7k1](/packages/luoyy-ali-oss-storage)[alphasnow/aliyun-oss-flysystem

Flysystem adapter for the Aliyun storage

14270.2k8](/packages/alphasnow-aliyun-oss-flysystem)

PHPackages © 2026

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